home *** CD-ROM | disk | FTP | other *** search
/ ETO Development Tools 1 / ETO Development Tools 1.iso / Essentials / MPW 411 / CIncludesHelp next >
Text File  |  1990-07-19  |  3MB  |  89,910 lines

  1. æKY CopyrightNotice
  2. æC  Copyright Apple Computer, Inc. 1985-1990, All rights reserved.
  3. 411 - CIncludes Help - QR 1 Release.
  4. Friday, July 6, 1990 1:22:42 PM
  5.  
  6. æKY Help
  7. CIncludesHelp
  8. æKL AboutCIncludesHelp.h
  9. ADSP.h
  10. Aliases.h
  11. AppleEvents.h
  12. Appletalk.h
  13. Balloons.h
  14. Controls.h
  15. CursorCtl.h
  16. DatabaseAccess.h
  17. DDEV.h
  18. Desk.h
  19. Deskbus.h
  20. Devices.h
  21. Dialogs.h
  22. DisAsmLookup.h
  23. DiskInit.h
  24. Disks.h
  25. Editions.h
  26. EPPC.h
  27. ErrMgr.h
  28. Errors.h
  29. Events.h
  30. Files.h
  31. FixMath.h
  32. Folders.h
  33. Fonts.h
  34. Globals
  35. Graf3D.h
  36. HyperXCmd.h
  37. Lists.h
  38. Math.h
  39. Memory.h
  40. Menus.h
  41. Notification.h
  42. OSEvents.h
  43. OSUtils.h
  44. Packages.h
  45. Palettes.h
  46. Perf.h
  47. Picker.h
  48. Power.h
  49. PPCToolBox.h
  50. PrintTraps.h
  51. Processes.h
  52. QDOffscreen.h
  53. Quickdraw.h
  54. Resources.h
  55. Retrace.h
  56. ROMDefs.h
  57. SANE.h
  58. Scrap.h
  59. Script.h
  60. SCSI.h
  61. Segload.h
  62. Serial.h
  63. ShutDown.h
  64. Slots.h
  65. Sound.h
  66. StandardFile.h
  67. Start.h
  68. Strings.h
  69. SysEqu.h
  70. TextEdit.h
  71. Timer.h
  72. ToolUtils.h
  73. Types.h
  74. Video.h
  75. Windows.h
  76.  
  77. StdCLib
  78.  
  79. Assert.h
  80. Ctype.h
  81. Errno.h
  82. FCntl.h
  83. Float.h
  84. IOCtl.h
  85. Limits.h
  86. Locale.h
  87. Math.h
  88. SetJmp.h
  89. Signal.h
  90. StdArg.h
  91. StdDef.h
  92. StdIO.h
  93. StdLib.h
  94. String.h
  95. Time.h
  96.  
  97. æKY AboutCincludesHelp.h
  98. æC
  99.  
  100. Version 1.0 Beta:
  101.  
  102. This version contains the InsideMacintosh Volume VI information.
  103.  
  104. æKY ADSP.h
  105. æKL 
  106. attnBufSize
  107. dspAttention
  108. dspCLDeny
  109. dspCLInit
  110. dspCLListen
  111. dspClose
  112. dspCLRemove
  113. dspInit
  114. dspNewCID
  115. dspOpen
  116. dspOptions
  117. DSPParamBlock
  118. DSPPBPtr
  119. dspRead
  120. dspRemove
  121. dspReset
  122. dspStatus
  123. dspWrite
  124. eAttention
  125. eClosed
  126. eFwdReset
  127. errAborted
  128. errAttention
  129. errFwdReset
  130. errOpening
  131. errRefNum
  132. errState
  133. eTearDown
  134. ocAccept
  135. ocEstablish
  136. ocPassive
  137. ocRequest
  138. sClosed
  139. sClosing
  140. sListening
  141. sOpen
  142. sOpening
  143. sPassive
  144. TPCCB
  145. TRattnParams
  146. TRCCB
  147. TRcloseParams
  148. TRinitParams
  149. TRioParams
  150. TRnewcidParams
  151. TRopenParams
  152. TRoptionParams
  153. TRstatusParams
  154.  
  155. æKY errRefNum
  156. æFc ADSP.h
  157. æT #define
  158. æD 
  159. /*         constants                                                     
  160.  
  161.  result codes */
  162.  
  163. #define errRefNum -1280 /* bad connection refNum */
  164. æC 
  165.  
  166. æKY errAborted
  167. æFc ADSP.h
  168. æT #define
  169. æD #define errAborted -1279 /* control call was aborted */
  170. æC 
  171.  
  172. æKY errState
  173. æFc ADSP.h
  174. æT #define
  175. æD #define errState -1278 /* bad connection state for this operation */
  176. æC 
  177.  
  178. æKY errOpening
  179. æFc ADSP.h
  180. æT #define
  181. æD #define errOpening -1277 /* open connection request was denied */
  182. æC 
  183.  
  184. æKY errAttention
  185. æFc ADSP.h
  186. æT #define
  187. æD #define errAttention -1276 /* attention message too long */
  188. æC 
  189.  
  190. æKY errFwdReset
  191. æFc ADSP.h
  192. æT #define
  193. æD #define errFwdReset -1275 /* read terminated by forward reset */
  194. æC 
  195.  
  196. æKY dspInit
  197. æFc ADSP.h
  198. æT #define
  199. æD 
  200. /*  control codes */
  201.  
  202. #define dspInit 255 /* create a new connection end */
  203. æC 
  204.  
  205. æKY dspRemove
  206. æFc ADSP.h
  207. æT #define
  208. æD #define dspRemove 254 /* remove a connection end */
  209. æC 
  210.  
  211. æKY dspOpen
  212. æFc ADSP.h
  213. æT #define
  214. æD #define dspOpen 253 /* open a connection */
  215. æC 
  216.  
  217. æKY dspClose
  218. æFc ADSP.h
  219. æT #define
  220. æD #define dspClose 252 /* close a connection */
  221. æC 
  222.  
  223. æKY dspCLInit
  224. æFc ADSP.h
  225. æT #define
  226. æD #define dspCLInit 251 /* create a connection listener */
  227. æC 
  228.  
  229. æKY dspCLRemove
  230. æFc ADSP.h
  231. æT #define
  232. æD #define dspCLRemove 250 /* remove a connection listener */
  233. æC 
  234.  
  235. æKY dspCLListen
  236. æFc ADSP.h
  237. æT #define
  238. æD #define dspCLListen 249 /* post a listener request */
  239. æC 
  240.  
  241. æKY dspCLDeny
  242. æFc ADSP.h
  243. æT #define
  244. æD #define dspCLDeny 248 /* deny an open connection request */
  245. æC 
  246.  
  247. æKY dspStatus
  248. æFc ADSP.h
  249. æT #define
  250. æD #define dspStatus 247 /* get status of connection end */
  251. æC 
  252.  
  253. æKY dspRead
  254. æFc ADSP.h
  255. æT #define
  256. æD #define dspRead 246 /* read data from the connection */
  257. æC 
  258.  
  259. æKY dspWrite
  260. æFc ADSP.h
  261. æT #define
  262. æD #define dspWrite 245 /* write data on the connection */
  263. æC 
  264.  
  265. æKY dspAttention
  266. æFc ADSP.h
  267. æT #define
  268. æD #define dspAttention 244 /* send an attention message */
  269. æC 
  270.  
  271. æKY dspOptions
  272. æFc ADSP.h
  273. æT #define
  274. æD #define dspOptions 243 /* set connection end options */
  275. æC 
  276.  
  277. æKY dspReset
  278. æFc ADSP.h
  279. æT #define
  280. æD #define dspReset 242 /* forward reset the connection */
  281. æC 
  282.  
  283. æKY dspNewCID
  284. æFc ADSP.h
  285. æT #define
  286. æD #define dspNewCID 241 /* generate a cid for a connection end */
  287. æC 
  288.  
  289. æKY ocRequest
  290. æFc ADSP.h
  291. æT #define
  292. æD 
  293. /*  connection opening modes */
  294.  
  295. #define ocRequest 1 /* request a connection with remote */
  296. æC 
  297.  
  298. æKY ocPassive
  299. æFc ADSP.h
  300. æT #define
  301. æD #define ocPassive 2 /* wait for a connection request from remote */
  302. æC 
  303.  
  304. æKY ocAccept
  305. æFc ADSP.h
  306. æT #define
  307. æD #define ocAccept 3 /* accept request as delivered by listener */
  308. æC 
  309.  
  310. æKY ocEstablish
  311. æFc ADSP.h
  312. æT #define
  313. æD #define ocEstablish 4 /* consider connection to be open */
  314. æC 
  315.  
  316. æKY sListening
  317. æFc ADSP.h
  318. æT #define
  319. æD 
  320. /*  connection end states */
  321.  
  322. #define sListening 1 /* for connection listeners */
  323. æC 
  324.  
  325. æKY sPassive
  326. æFc ADSP.h
  327. æT #define
  328. æD #define sPassive 2 /* waiting for a connection request from remote */
  329. æC 
  330.  
  331. æKY sOpening
  332. æFc ADSP.h
  333. æT #define
  334. æD #define sOpening 3 /* requesting a connection with remote */
  335. æC 
  336.  
  337. æKY sOpen
  338. æFc ADSP.h
  339. æT #define
  340. æD #define sOpen 4 /* connection is open */
  341. æC 
  342.  
  343. æKY sClosing
  344. æFc ADSP.h
  345. æT #define
  346. æD #define sClosing 5 /* connection is being torn down */
  347. æC 
  348.  
  349. æKY sClosed
  350. æFc ADSP.h
  351. æT #define
  352. æD #define sClosed 6 /* connection end state is closed */
  353. æC 
  354.  
  355. æKY eClosed
  356. æFc ADSP.h
  357. æT #define
  358. æD 
  359. /*  client event flags */
  360.  
  361. #define eClosed 0x80 /* received connection closed advice */
  362. æC 
  363.  
  364. æKY eTearDown
  365. æFc ADSP.h
  366. æT #define
  367. æD #define eTearDown 0x40 /* connection closed due to broken connection */
  368. æC 
  369.  
  370. æKY eAttention
  371. æFc ADSP.h
  372. æT #define
  373. æD #define eAttention 0x20 /* received attention message */
  374. æC 
  375.  
  376. æKY eFwdReset
  377. æFc ADSP.h
  378. æT #define
  379. æD #define eFwdReset 0x10 /* received forward reset advice */
  380. æC 
  381.  
  382. æKY attnBufSize
  383. æFc ADSP.h
  384. æT #define
  385. æD 
  386. /*  miscellaneous constants */
  387.  
  388. #define attnBufSize 570 /* size of client attention buffer */
  389. æC 
  390.  
  391. æKY TRCCB
  392. TPCCB
  393. æFc ADSP.h
  394. æT struct
  395. æD struct TRCCB {
  396.     unsigned char *ccbLink; /* link to next ccb */
  397.     unsigned short refNum; /* user reference number */
  398.     unsigned short state; /* state of the connection end */
  399.     unsigned char userFlags; /* flags for unsolicited connection events */
  400.     unsigned char localSocket; /* socket number of this connection end */
  401.     AddrBlock remoteAddress; /* internet address of remote end */
  402.     unsigned short attnCode; /* attention code received */
  403.     unsigned short attnSize; /* size of received attention data */
  404.     unsigned char *attnPtr; /* ptr to received attention data */
  405.     unsigned char reserved[220]; /* for adsp internal use */
  406. };
  407.  
  408. typedef struct TRCCB TRCCB;
  409. typedef TRCCB *TPCCB;
  410.  
  411. æC 
  412.  
  413. æKY TRinitParams
  414. æFc ADSP.h
  415. æT struct
  416. æD struct TRinitParams {
  417.     TPCCB ccbPtr; /* pointer to connection control block */
  418.     ProcPtr userRoutine; /* client routine to call on event */
  419.     unsigned short sendQSize; /* size of send queue (0..64K bytes) */
  420.     unsigned char *sendQueue; /* client passed send queue buffer */
  421.     unsigned short recvQSize; /* size of receive queue (0..64K bytes) */
  422.     unsigned char *recvQueue; /* client passed receive queue buffer */
  423.     unsigned char *attnPtr; /* client passed receive attention buffer */
  424.     unsigned char localSocket; /* local socket number */
  425. };
  426.  
  427. typedef struct TRinitParams TRinitParams;
  428. /*  init connection end parameters  */
  429. æC 
  430.  
  431. æKY TRopenParams
  432. æFc ADSP.h
  433. æT struct
  434. æD struct TRopenParams {
  435.     unsigned short localCID; /* local connection id */
  436.     unsigned short remoteCID; /* remote connection id */
  437.     AddrBlock remoteAddress; /* address of remote end */
  438.     AddrBlock filterAddress; /* address filter */
  439.     unsigned long sendSeq; /* local send sequence number */
  440.     unsigned short sendWindow; /* send window size */
  441.     unsigned long recvSeq; /* receive sequence number */
  442.     unsigned long attnSendSeq; /* attention send sequence number */
  443.     unsigned long attnRecvSeq; /* attention receive sequence number */
  444.     unsigned char ocMode; /* open connection mode */
  445.     unsigned char ocInterval; /* open connection request retry interval */
  446.     unsigned char ocMaximum; /* open connection request retry maximum */
  447. };
  448.  
  449. typedef struct TRopenParams TRopenParams;
  450. /*  open connection parameters  */
  451. æC 
  452.  
  453. æKY TRcloseParams
  454. æFc ADSP.h
  455. æT struct
  456. æD struct TRcloseParams {
  457.     unsigned char abort; /* abort connection immediately if non-zero */
  458. };
  459.  
  460. typedef struct TRcloseParams TRcloseParams;
  461. /*  close connection parameters  */
  462. æC 
  463.  
  464. æKY TRstatusParams
  465. æFc ADSP.h
  466. æT struct
  467. æD struct TRstatusParams {
  468.     TPCCB ccbPtr; /* pointer to ccb */
  469.     unsigned short sendQPending; /* pending bytes in send queue */
  470.     unsigned short sendQFree; /* available buffer space in send queue*/
  471.     unsigned short recvQPending; /* pending bytes in receive queue */
  472.     unsigned short recvQFree; /* available buffer space in receive queue */
  473. };
  474.  
  475. typedef struct TRstatusParams TRstatusParams;
  476. /*  client status parameter block  */
  477. æC 
  478.  
  479. æKY TRioParams
  480. æFc ADSP.h
  481. æT struct
  482. æD struct TRioParams {
  483.     unsigned short reqCount; /* requested number of bytes */
  484.     unsigned short actCount; /* actual number of bytes */
  485.     unsigned char *dataPtr; /* pointer to data buffer */
  486.     unsigned char eom; /* indicates logical end of message */
  487.     unsigned char flush; /* send data now */
  488. };
  489.  
  490. typedef struct TRioParams TRioParams;
  491. /*  read/write parameter block  */
  492. æC 
  493.  
  494. æKY TRattnParams
  495. æFc ADSP.h
  496. æT struct
  497. æD struct TRattnParams {
  498.     unsigned short attnCount; /* client attention code */
  499.     unsigned short attnSize; /* size of attention data */
  500.     unsigned char *attnData; /* pointer to attention data */
  501.     unsigned char attnInterval; /* retransmit timer in 10-tick intervals */
  502. };
  503.  
  504. typedef struct TRattnParams TRattnParams;
  505. /*  attention parameter block  */
  506. æC 
  507.  
  508. æKY TRoptionParams
  509. æFc ADSP.h
  510. æT struct
  511. æD struct TRoptionParams {
  512.     unsigned short sendBlocking; /* quantum for data packets */
  513.     unsigned char sendTimer; /* send timer in 10-tick intervals */
  514.     unsigned char rtmtTimer; /* retransmit timer in 10-tick intervals */
  515.     unsigned char badSeqMax; /* threshold for sending retransmit advice */
  516.     unsigned char useCheckSum; /* use ddp packet checksum */
  517. };
  518.  
  519. typedef struct TRoptionParams TRoptionParams;
  520. /*  client send option parameter block  */
  521. æC 
  522.  
  523. æKY TRnewcidParams
  524. æFc ADSP.h
  525. æT struct
  526. æD struct TRnewcidParams {
  527.     unsigned short newcid; /* new connection id returned */
  528. };
  529.  
  530. typedef struct TRnewcidParams TRnewcidParams;
  531. /*  new cid parameters  */
  532. æC 
  533.  
  534. æKY DSPParamBlock
  535. DSPPBPtr
  536. æFc ADSP.h
  537. æT struct
  538. æD union DSPParamBlock {
  539.     QElem *qLink;
  540.     short qType;
  541.     short ioTrap;
  542.     Ptr ioCmdAddr;
  543.     ProcPtr ioCompletion;
  544.     OSErr ioResult;
  545.     char *ioNamePtr;
  546.     short ioVRefNum;
  547.     short ioCRefNum; /* adsp driver refnum */
  548.     short csCode; /* adsp driver control code */
  549.     long qStatus; /* adsp internal use */
  550.     short ccbRefNum; /* connection end reNum*/
  551.     union ;
  552.     {
  553.     TRinitParams initParams; /* dspInit, dspCLInit */
  554.     TRopenParams openParams; /* dspOpen, dspCLListen, dspCLDeny */
  555.     TRcloseParams closeParams; /* dspClose, dspRemove */
  556.     TRioParams ioParams; /* dspRead, dspWrite */
  557.     TRattnParams attnParams; /* dspAttention */
  558.     TRstatusParams statusParams; /* dspStatus */
  559.     TRoptionParams optionParams; /* dspOptions */
  560.     TRnewcidParams newCIDParams; /* dspNewCID */
  561. };
  562.  
  563. typedef union DSPParamBlock DSPParamBlock;
  564.  
  565. typedef DSPParamBlock *DSPPBPtr;
  566.  
  567. /*  ADSP CntrlParam ioQElement  */
  568. æC 
  569.  
  570.  
  571. æKY Aliases.h
  572. æKL CanonifyFile
  573. GetAliasInfo
  574. MatchAlias
  575. NewAlias
  576. NewAliasMinimal
  577. NewAliasMinimalFromFullpath
  578. ResolveAlias
  579. SelectAlias
  580. UpdateAlias
  581.  
  582. AliasFilterProcPtr
  583. AliasHandle
  584. AliasInfoType
  585. AliasPtr
  586. AliasRecord
  587. asiAliasName
  588. asiParentName
  589. asiServerName
  590. asiVolumeName
  591. asiZoneName
  592. CanonicalFileSpec
  593. CanonicalFileSpecList
  594. kARMmountVol
  595. kARMmultVols
  596. kARMnoUI
  597. kARMsearch
  598. kARMsearchMore
  599. kARMsearchRelFirst
  600. ModalFilterWithCallback
  601. rAliasType
  602.  
  603. æKY rAliasType
  604. æFc Aliases.h
  605. æT #define
  606. æD 
  607. /* 
  608.     Constants 
  609.  */
  610.  
  611. #define rAliasType 'alis' /* Aliases are stored as resources of this type */
  612. æC 
  613.  
  614. æKY kARMmountVol
  615. æFc Aliases.h
  616. æT #define
  617. æD 
  618. /*  define alias resolution action rules mask */
  619.  
  620. #define kARMmountVol 0x00000001 /* mount the volume automatically */
  621. æC 
  622.  
  623. æKY kARMnoUI
  624. æFc Aliases.h
  625. æT #define
  626. æD #define kARMnoUI 0x00000002 /* no user interface allowed during resolution */
  627. æC 
  628.  
  629. æKY kARMmultVols
  630. æFc Aliases.h
  631. æT #define
  632. æD #define kARMmultVols 0x00000008 /* search on multiple volumes */
  633. æC 
  634.  
  635. æKY kARMsearch
  636. æFc Aliases.h
  637. æT #define
  638. æD #define kARMsearch 0x00000100 /* search quickly */
  639. æC 
  640.  
  641. æKY kARMsearchMore
  642. æFc Aliases.h
  643. æT #define
  644. æD #define kARMsearchMore 0x00000200 /* search further */
  645. æC 
  646.  
  647. æKY kARMsearchRelFirst
  648. æFc Aliases.h
  649. æT #define
  650. æD #define kARMsearchRelFirst 0x00000400 /* search target on a relative path first */
  651. æC 
  652.  
  653. æKY asiZoneName
  654. æFc Aliases.h
  655. æT #define
  656. æD 
  657. /*  define alias record information types */
  658.  
  659. #define asiZoneName -3 /* get zone name */
  660. æC 
  661.  
  662. æKY asiServerName
  663. æFc Aliases.h
  664. æT #define
  665. æD #define asiServerName -2 /* get server name */
  666. æC 
  667.  
  668. æKY asiVolumeName
  669. æFc Aliases.h
  670. æT #define
  671. æD #define asiVolumeName -1 /* get volume name */
  672. æC 
  673.  
  674. æKY asiAliasName
  675. æFc Aliases.h
  676. æT #define
  677. æD #define asiAliasName 0 /* get aliased file/folder/volume name */
  678. æC 
  679.  
  680. æKY asiParentName
  681. æFc Aliases.h
  682. æT #define
  683. æD #define asiParentName 1 /* get parent folder name */
  684. æC 
  685.  
  686. æKY AliasInfoType
  687. æFc Aliases.h
  688. æT typedef
  689. æD typedef short AliasInfoType; /* alias record information type */
  690. æC 
  691.  
  692. æKY AliasFilterProcPtr
  693. æFc Aliases.h
  694. æT typedef
  695. æD typedef pascal Boolean (*AliasFilterProcPtr) (CInfoPBPtr cpbPtr, /*I*/
  696.  Boolean *quitFlag, /*O*/
  697.  Ptr yourDataPtr); /*I*/
  698. æC 
  699.  
  700. æKY ModalFilterWithCallback
  701. æFc Aliases.h
  702. æT typedef
  703. æD typedef pascal Boolean (*ModalFilterWithCallback) (DialogPtr theDialog, /*I*/
  704.  EventRecord *theEvent, /*I*/
  705.   short *itemHit, /*O*/
  706.   Ptr yourDataPtr); /*I*/
  707. æC 
  708.  
  709. æKY CanonicalFileSpec
  710. CanonicalFileSpecList
  711. æFc Aliases.h
  712. æT struct
  713. æD struct CanonicalFileSpec {
  714.     Short vRefNum; /* volume reference number */
  715.     long dirID; /* directory ID */
  716.     Str63 fileName; /* file name */
  717. };
  718.  
  719. typedef struct CanonicalFileSpec CanonicalFileSpec;
  720. typedef CanonicalFileSpec *CanonicalFileSpecList;
  721.  
  722. æC 
  723.  
  724. æKY AliasRecord
  725. AliasPtr
  726. AliasHandle
  727. æFc Aliases.h
  728. æT struct
  729. æD struct AliasRecord {
  730.     OSType userType; /* appl stored type like creator type */
  731.     unsigned short aliasSize; /* alias record size in bytes, for appl usage*/
  732. };
  733.  
  734. typedef struct AliasRecord AliasRecord;
  735. typedef AliasRecord *AliasPtr, **AliasHandle;
  736.  
  737. /*  define the alias record that will be the blackbox for the caller  */
  738. æC 
  739.  
  740. æKY CanonifyFile
  741. æFc Aliases.h
  742. æT Function
  743. æTN A823
  744. æD pascal OSErr CanonifyFile(short vRefNum,long dirID,const Str255 fileName,
  745.     CanonicalFileSpec *canonicalFile)
  746.     = {0x7001,0xA823}; 
  747. æDT OSErr myVariable = CanonifyFile((short) vRefNum,(long) dirID,(const Str255) fileName,(
  748.     CanonicalFileSpec) * canonicalFile);
  749. æC 
  750.  
  751. æKY NewAlias
  752. æFc Aliases.h
  753. æT Function
  754. æTN A823
  755. æD pascal OSErr NewAlias(const CanonicalFileSpec *fromFile,const CanonicalFileSpec *target,
  756.     AliasHandle *alias)
  757.     = {0x7002,0xA823}; 
  758. æDT OSErr myVariable = NewAlias((const CanonicalFileSpec *) fromFile,(const CanonicalFileSpec *) target,(
  759.     AliasHandle) * alias);
  760. æC 
  761.  
  762. æKY NewAliasMinimal
  763. æFc Aliases.h
  764. æT Function
  765. æTN A823
  766. æD pascal OSErr NewAliasMinimal(const CanonicalFileSpec *target,AliasHandle *alias)
  767.     = {0x7008,0xA823}; 
  768. æDT OSErr myVariable = NewAliasMinimal((const CanonicalFileSpec *) target,(AliasHandle *) alias);
  769. æC 
  770.  
  771. æKY NewAliasMinimalFromFullpath
  772. æFc Aliases.h
  773. æT Function
  774. æTN A823
  775. æD pascal OSErr NewAliasMinimalFromFullpath(short fullpathLength,const unsigned char *fullpath,
  776.     const Str31 zoneName,const Str31 serverName,AliasHandle *alias)
  777.     = {0x7009,0xA823}; 
  778. æDT OSErr myVariable = NewAliasMinimalFromFullpath((short) fullpathLength,(const unsigned char *) fullpath,(
  779.     const) Str31 zoneName,(const Str31) serverName,(AliasHandle *) alias);
  780. æC 
  781.  
  782. æKY ResolveAlias
  783. æFc Aliases.h
  784. æT Function
  785. æTN A823
  786. æD pascal OSErr ResolveAlias(const CanonicalFileSpec *fromFile,AliasHandle alias,
  787.     CanonicalFileSpec *target,Boolean *wasChanged)
  788.     = {0x7003,0xA823}; 
  789. æDT OSErr myVariable = ResolveAlias((const CanonicalFileSpec *) fromFile,(AliasHandle) alias,(
  790.     CanonicalFileSpec) * target,(Boolean *) wasChanged);
  791. æC 
  792.  
  793. æKY SelectAlias
  794. æFc Aliases.h
  795. æT Function
  796. æTN A823
  797. æD pascal OSErr SelectAlias(const CanonicalFileSpec *fromFile,const Str31 fileTypeName,
  798.     Boolean aliasFilter,AliasHandle alias,CanonicalFileSpec *target,Boolean *wasChanged,
  799.     Boolean filterProc,Ptr yourDataPtr)
  800.     = {0x7004,0xA823}; 
  801. æDT OSErr myVariable = SelectAlias((const CanonicalFileSpec *) fromFile,(const Str31) fileTypeName,()
  802.     Boolean aliasFilter,(AliasHandle) alias,(CanonicalFileSpec *) target,(Boolean *) wasChanged,()
  803.     Boolean filterProc,(Ptr) yourDataPtr);
  804. æC 
  805.  
  806. æKY GetAliasInfo
  807. æFc Aliases.h
  808. æT Function
  809. æTN A823
  810. æD pascal OSErr GetAliasInfo(const AliasHandle alias,AliasInfoType index,const Str63 theString)
  811.     = {0x7007,0xA823}; 
  812. æDT OSErr myVariable = GetAliasInfo((const AliasHandle) alias,(AliasInfoType) index,(const Str63) theString);
  813. æC 
  814.  
  815. æKY MatchAlias
  816. æFc Aliases.h
  817. æT Function
  818. æTN A823
  819. æD pascal OSErr MatchAlias(const CanonicalFileSpec *fromFile,unsigned long rulesMask,
  820.     const AliasHandle alias,Short *aliasCount,const CanonicalFileSpecList *aliasList,
  821.     Boolean *needsUpdate,Boolean aliasFilter,Ptr yourDataPtr)
  822.     = {0x7005,0xA823}; 
  823. æDT OSErr myVariable = MatchAlias((const CanonicalFileSpec *) fromFile,(unsigned long) rulesMask,(
  824.     const) AliasHandle alias,(Short *) aliasCount,(const CanonicalFileSpecList *) aliasList,(
  825.     Boolean) * needsUpdate,(Boolean) aliasFilter,(Ptr) yourDataPtr);
  826. æC 
  827.  
  828. æKY UpdateAlias
  829. æFc Aliases.h
  830. æT Function
  831. æTN A823
  832. æD pascal OSErr UpdateAlias(const CanonicalFileSpec *fromFile,const CanonicalFileSpec *target,
  833.     AliasHandle alias,Boolean *wasChanged)
  834.     = {0x7006,0xA823}; 
  835. æDT OSErr myVariable = UpdateAlias((const CanonicalFileSpec *) fromFile,(const CanonicalFileSpec *) target,()
  836.     AliasHandle alias,(Boolean *) wasChanged);
  837. æC 
  838.  
  839.  
  840. æKY AppleEvents.h
  841. æKL AEAddEvtToTable
  842. AECoerceDesc
  843. AECountListElems
  844. AECreateAevt
  845. AECreateDispatchTable
  846. AECreateList
  847. AEDeleteIndex
  848. AEDeleteKey
  849. AEDisposeAEDesc
  850. AEDisposeAEList
  851. AEGetAddress
  852. AEGetArray
  853. AEGetDispatchTableRsrc
  854. AEGetEventClassAndID
  855. AEGetInteractLevel
  856. AEGetKeyDesc
  857. AEGetKeyPtr
  858. AEGetNthDesc
  859. AEGetNthPtr
  860. AEGetRefCon
  861. AEGetTableEntry
  862. AEInit
  863. AEInteractionAllowed
  864. AEInteractWithUser
  865. AEProcessAppleEvent
  866. AEPutArray
  867. AEPutDesc
  868. AEPutKeyDesc
  869. AEPutKeyPtr
  870. AEPutPtr
  871. AEQuit
  872. AEResetTimer
  873. AESend
  874. AESetAddressByPSN
  875. AESetAddressBySessionID
  876. AESetAddressBySignature
  877. AESetAddressByTargetID
  878. AEWhichAevt
  879.  
  880. AEAddress
  881. AEAddressHndl
  882. AEAddressPtr
  883. AEArrayType
  884. AEDesc
  885. AEInteractAllowed
  886. AEKeyDesc
  887. AEList
  888. DescType
  889. EventClass
  890. EventID
  891. kAEAliasType
  892. kAEAlwaysInteract
  893. kAEBadListElement
  894. kAEBooleanType
  895. kAECanInteract
  896. kAECanSwitchLayer
  897. kAECoercionFail
  898. kAECorruptData
  899. kAEDataArray
  900. kAEDescArray
  901. kAEDescNotFound
  902. kAEDirectObjectKeyword
  903. kAEDontReconnect
  904. kAEEventNotFound
  905. kAEEventNotInTable
  906. kAEFalseType
  907. kAEHandleArray
  908. kAEHighPriority
  909. kAEInteractionWithSelf
  910. kAEInteractWithAll
  911. kAEInteractWithLocal
  912. kAEKeyDescArray
  913. kAEListType
  914. kAELongType
  915. kAENeverInteract
  916. kAENoReply
  917. kAENormalPriority
  918. kAENotAEList
  919. kAENotAppleEvent
  920. kAENoUserInteraction
  921. kAEOpenApplication
  922. kAEOpenDocuments
  923. kAEPackedArray
  924. kAEPrintDocuments
  925. kAEQueueReply
  926. kAEQuitApplication
  927. kAEReplyNotValid
  928. kAETimeoutErr
  929. kAETrueType
  930. kAEUnknownInteract
  931. kAEUnknownSendMode
  932. KAEWaitCanceled
  933. kAEWaitReply
  934. kAEWantReceipt
  935. kAEWildType
  936. kAEWrongDataType
  937. kAEWrongVersion
  938. kAutoGenerateRefcon
  939. kCoreEventClass
  940. KeyWord
  941.  
  942. æKY kAELongType
  943. æFc AppleEvents.h
  944. æT #define
  945. æD #define kAELongType 'long'
  946. æC 
  947.  
  948. æKY kAEListType
  949. æFc AppleEvents.h
  950. æT #define
  951. æD #define kAEListType 'list'
  952. æC 
  953.  
  954. æKY kAEWildType
  955. æFc AppleEvents.h
  956. æT #define
  957. æD #define kAEWildType '****'
  958. æC 
  959.  
  960. æKY kAEBooleanType
  961. æFc AppleEvents.h
  962. æT #define
  963. æD #define kAEBooleanType 'bool'
  964. æC 
  965.  
  966. æKY kAETrueType
  967. æFc AppleEvents.h
  968. æT #define
  969. æD #define kAETrueType 'true'
  970. æC 
  971.  
  972. æKY kAEFalseType
  973. æFc AppleEvents.h
  974. æT #define
  975. æD #define kAEFalseType 'fals'
  976. æC 
  977.  
  978. æKY kAEAliasType
  979. æFc AppleEvents.h
  980. æT #define
  981. æD #define kAEAliasType 'alis'
  982. æC 
  983.  
  984. æKY kAEDirectObjectKeyword
  985. æFc AppleEvents.h
  986. æT #define
  987. æD #define kAEDirectObjectKeyword '----'
  988. æC 
  989.  
  990. æKY kCoreEventClass
  991. æFc AppleEvents.h
  992. æT #define
  993. æD #define kCoreEventClass 'aevt'
  994. æC 
  995.  
  996. æKY kAEOpenApplication
  997. æFc AppleEvents.h
  998. æT #define
  999. æD #define kAEOpenApplication 'oapp'
  1000. æC 
  1001.  
  1002. æKY kAEOpenDocuments
  1003. æFc AppleEvents.h
  1004. æT #define
  1005. æD #define kAEOpenDocuments 'odoc'
  1006. æC 
  1007.  
  1008. æKY kAEPrintDocuments
  1009. æFc AppleEvents.h
  1010. æT #define
  1011. æD #define kAEPrintDocuments 'pdoc'
  1012. æC 
  1013.  
  1014. æKY kAEQuitApplication
  1015. æFc AppleEvents.h
  1016. æT #define
  1017. æD #define kAEQuitApplication 'quit'
  1018. æC 
  1019.  
  1020. æKY kAENoReply
  1021. æFc AppleEvents.h
  1022. æT #define
  1023. æD #define kAENoReply 0x00000001 /* Sender doesn't want a reply to event */
  1024. æC 
  1025.  
  1026. æKY kAEQueueReply
  1027. æFc AppleEvents.h
  1028. æT #define
  1029. æD #define kAEQueueReply 0x00000002 /* Sender wants a reply but won't wait */
  1030. æC 
  1031.  
  1032. æKY kAEWaitReply
  1033. æFc AppleEvents.h
  1034. æT #define
  1035. æD #define kAEWaitReply 0x00000003 /* Sender wants a reply and will be waiting */
  1036. æC 
  1037.  
  1038. æKY kAENeverInteract
  1039. æFc AppleEvents.h
  1040. æT #define
  1041. æD #define kAENeverInteract 0x00000010 /* Server should not interact with user */
  1042. æC 
  1043.  
  1044. æKY kAECanInteract
  1045. æFc AppleEvents.h
  1046. æT #define
  1047. æD #define kAECanInteract 0x00000020 /* Server may try to interact with user */
  1048. æC 
  1049.  
  1050. æKY kAEAlwaysInteract
  1051. æFc AppleEvents.h
  1052. æT #define
  1053. æD #define kAEAlwaysInteract 0x00000030 /* Server should always interact with user */
  1054. æC 
  1055.  
  1056. æKY kAECanSwitchLayer
  1057. æFc AppleEvents.h
  1058. æT #define
  1059. æD #define kAECanSwitchLayer 0x00000040 /* Interaction may switch layer */
  1060. æC 
  1061.  
  1062. æKY kAEDontReconnect
  1063. æFc AppleEvents.h
  1064. æT #define
  1065. æD #define kAEDontReconnect 0x00000080 /* don't reconnect if there is a sessClosedErr */
  1066. æC 
  1067.  
  1068. æKY kAEWantReceipt
  1069. æFc AppleEvents.h
  1070. æT #define
  1071. æD #define kAEWantReceipt nReturnReceipt /* Send wants a receipt of message */
  1072. æC 
  1073.  
  1074. æKY kAENormalPriority
  1075. æFc AppleEvents.h
  1076. æT #define
  1077. æD #define kAENormalPriority 0x00000000 /* Post message at the end of event queue */
  1078. æC 
  1079.  
  1080. æKY kAEHighPriority
  1081. æFc AppleEvents.h
  1082. æT #define
  1083. æD #define kAEHighPriority nAttnMsg /* Post message at the front of the event queue */
  1084. æC 
  1085.  
  1086. æKY kAutoGenerateRefcon
  1087. æFc AppleEvents.h
  1088. æT #define
  1089. æD #define kAutoGenerateRefcon 0
  1090. æC 
  1091.  
  1092. æKY kAEEventNotInTable
  1093. æFc AppleEvents.h
  1094. æT #define
  1095. æD #define kAEEventNotInTable 0 /* Passed to the general dispatch proc if the event received was not in the dispatch table */
  1096. æC 
  1097.  
  1098. æKY kAECoercionFail
  1099. æFc AppleEvents.h
  1100. æT #define
  1101. æD 
  1102. /* Error messages in response to reading and writing buffer contents */
  1103.  
  1104. #define kAECoercionFail -1700
  1105. æC 
  1106.  
  1107. æKY kAEDescNotFound
  1108. æFc AppleEvents.h
  1109. æT #define
  1110. æD #define kAEDescNotFound -1701
  1111. æC 
  1112.  
  1113. æKY kAECorruptData
  1114. æFc AppleEvents.h
  1115. æT #define
  1116. æD #define kAECorruptData -1702
  1117. æC 
  1118.  
  1119. æKY kAEWrongDataType
  1120. æFc AppleEvents.h
  1121. æT #define
  1122. æD #define kAEWrongDataType -1703
  1123. æC 
  1124.  
  1125. æKY kAENotAEList
  1126. æFc AppleEvents.h
  1127. æT #define
  1128. æD #define kAENotAEList -1704
  1129. æC 
  1130.  
  1131. æKY kAEBadListElement
  1132. æFc AppleEvents.h
  1133. æT #define
  1134. æD #define kAEBadListElement -1705
  1135. æC 
  1136.  
  1137. æKY kAEWrongVersion
  1138. æFc AppleEvents.h
  1139. æT #define
  1140. æD #define kAEWrongVersion -1706
  1141. æC 
  1142.  
  1143. æKY kAENotAppleEvent
  1144. æFc AppleEvents.h
  1145. æT #define
  1146. æD #define kAENotAppleEvent -1707
  1147. æC 
  1148.  
  1149. æKY kAEEventNotFound
  1150. æFc AppleEvents.h
  1151. æT #define
  1152. æD 
  1153. /* Error messages in response to sending/receiving a message */
  1154.  
  1155. #define kAEEventNotFound -1708 /* The event isn't in the supplied event table */
  1156. æC 
  1157.  
  1158. æKY kAEReplyNotValid
  1159. æFc AppleEvents.h
  1160. æT #define
  1161. æD #define kAEReplyNotValid -1709 /* AEResetTimer was passed an invalid reply */
  1162. æC 
  1163.  
  1164. æKY kAEUnknownSendMode
  1165. æFc AppleEvents.h
  1166. æT #define
  1167. æD #define kAEUnknownSendMode -1710 /* Mode wasn't NoReply, WaitReply, QueueReply; or Interaction level is unknown */
  1168. æC 
  1169.  
  1170. æKY KAEWaitCanceled
  1171. æFc AppleEvents.h
  1172. æT #define
  1173. æD #define KAEWaitCanceled -1711 /* User cancelled out of wait loop for reply or receipt */
  1174. æC 
  1175.  
  1176. æKY kAETimeoutErr
  1177. æFc AppleEvents.h
  1178. æT #define
  1179. æD #define kAETimeoutErr -1712 /* AppleEvent time out */
  1180. æC 
  1181.  
  1182. æKY kAENoUserInteraction
  1183. æFc AppleEvents.h
  1184. æT #define
  1185. æD #define kAENoUserInteraction -1713 /* no user interaction allowed */
  1186. æC 
  1187.  
  1188. æKY AEArrayType
  1189. kAEDataArray
  1190. kAEPackedArray
  1191. kAEHandleArray
  1192. kAEDescArray
  1193. kAEKeyDescArray
  1194. æFc AppleEvents.h
  1195. æT enum
  1196. æD enum {kAEDataArray,kAEPackedArray,kAEHandleArray,kAEDescArray,kAEKeyDescArray};
  1197. typedef unsigned char AEArrayType;
  1198. æC 
  1199.  
  1200. æKY AEInteractAllowed
  1201. kAEUnknownInteract
  1202. kAEInteractionWithSelf
  1203. kAEInteractWithLocal
  1204. kAEInteractWithAll
  1205.  
  1206. æFc AppleEvents.h
  1207. æT enum
  1208. æD enum {kAEUnknownInteract,kAEInteractionWithSelf,kAEInteractWithLocal,kAEInteractWithAll};
  1209. typedef unsigned char AEInteractAllowed;
  1210. æC 
  1211.  
  1212. æKY AEList
  1213. æFc AppleEvents.h
  1214. æT typedef
  1215. æD typedef long AEList;
  1216. æC 
  1217.  
  1218. æKY KeyWord
  1219. æFc AppleEvents.h
  1220. æT typedef
  1221. æD typedef unsigned long KeyWord;
  1222. æC 
  1223.  
  1224. æKY EventClass
  1225. æFc AppleEvents.h
  1226. æT typedef
  1227. æD typedef unsigned long EventClass;
  1228. æC 
  1229.  
  1230. æKY EventID
  1231. æFc AppleEvents.h
  1232. æT typedef
  1233. æD typedef unsigned long EventID;
  1234. æC 
  1235.  
  1236. æKY DescType
  1237. æFc AppleEvents.h
  1238. æT typedef
  1239. æD typedef OSType DescType;
  1240. æC 
  1241.  
  1242. æKY AEAddress
  1243. AEAddressPtr
  1244. AEAddressHndl
  1245. æFc AppleEvents.h
  1246. æT struct
  1247. æD union AEAddress {
  1248.     ProcessSerialNumber receiverIDasPSN;
  1249.     OSType receiverIDasSig;
  1250.     long receiverIDasSess;
  1251.     TargetID receiverIDasTargetID;
  1252. };
  1253.  
  1254. typedef union AEAddress AEAddress;
  1255.  
  1256. typedef AEAddress *AEAddressPtr, **AEAddressHndl;
  1257.  
  1258. æC 
  1259.  
  1260. æKY AEDesc
  1261. æFc AppleEvents.h
  1262. æT struct
  1263. æD struct AEDesc {
  1264.     DescType descriptorType;
  1265.     union{
  1266.     Handle asDataHdl;
  1267.     AEList asAEList;
  1268.     }Boolean;
  1269. };
  1270.  
  1271. typedef struct AEDesc AEDesc;
  1272. æC 
  1273.  
  1274. æKY AEKeyDesc
  1275. æFc AppleEvents.h
  1276. æT struct
  1277. æD struct AEKeyDesc {
  1278.     KeyWord descKey;
  1279.     AEDesc descContent;
  1280. };
  1281.  
  1282. typedef struct AEKeyDesc AEKeyDesc;
  1283. æC 
  1284.  
  1285. æKY AEInit
  1286. æFc AppleEvents.h
  1287. æT Function
  1288. æD 
  1289. pascal OSErr AEInit(ProcPtr dispatchProc,ProcPtr coercionProc,ProcPtr nonAevtHandler); 
  1290. æDT OSErr myVariable = AEInit((ProcPtr) dispatchProc,(ProcPtr) coercionProc,(ProcPtr) nonAevtHandler);
  1291. æC 
  1292.  
  1293. æKY AEQuit
  1294. æFc AppleEvents.h
  1295. æT Function
  1296. æD 
  1297. pascal void AEQuit(void); 
  1298. æDT 
  1299. AEQuit()(void);
  1300. æC 
  1301.  
  1302. æKY AEPutPtr
  1303. æFc AppleEvents.h
  1304. æT Function
  1305. æD 
  1306. pascal OSErr AEPutPtr(AEList theList,long index,DescType typeCode,Ptr dataPtr,
  1307.     long dataSize); 
  1308. æDT OSErr myVariable = AEPutPtr((AEList) theList,(long) index,(DescType) typeCode,(Ptr) dataPtr,()
  1309.     long dataSize);
  1310. æC 
  1311.  
  1312. æKY AEPutDesc
  1313. æFc AppleEvents.h
  1314. æT Function
  1315. æD 
  1316. pascal OSErr AEPutDesc(AEList theList,long index,const AEDesc *theDesc); 
  1317. æDT OSErr myVariable = AEPutDesc((AEList) theList,(long) index,(const AEDesc *) theDesc);
  1318. æC 
  1319.  
  1320. æKY AEPutKeyPtr
  1321. æFc AppleEvents.h
  1322. æT Function
  1323. æD 
  1324. pascal OSErr AEPutKeyPtr(AEList theList,KeyWord key,DescType typeCode,Ptr dataPtr,
  1325.     long dataSize); 
  1326. æDT OSErr myVariable = AEPutKeyPtr((AEList) theList,(KeyWord) key,(DescType) typeCode,(Ptr) dataPtr,()
  1327.     long dataSize);
  1328. æC 
  1329.  
  1330. æKY AEPutKeyDesc
  1331. æFc AppleEvents.h
  1332. æT Function
  1333. æD 
  1334. pascal OSErr AEPutKeyDesc(AEList theList,KeyWord key,const AEDesc *theDesc); 
  1335. æDT OSErr myVariable = AEPutKeyDesc((AEList) theList,(KeyWord) key,(const AEDesc *) theDesc);
  1336. æC 
  1337.  
  1338. æKY AEGetNthPtr
  1339. æFc AppleEvents.h
  1340. æT Function
  1341. æD 
  1342. pascal OSErr AEGetNthPtr(AEList theList,long index,DescType desiredType,
  1343.     KeyWord *key,DescType *typeCode,Ptr dataPtr,long maxSize,long *actualSize); 
  1344. æDT OSErr myVariable = AEGetNthPtr((AEList) theList,(long) index,(DescType) desiredType,(
  1345.     KeyWord) * key,(DescType *) typeCode,(Ptr) dataPtr,(long) maxSize,(long *) actualSize);
  1346. æC 
  1347.  
  1348. æKY AEGetNthDesc
  1349. æFc AppleEvents.h
  1350. æT Function
  1351. æD 
  1352. pascal OSErr AEGetNthDesc(AEList theList,long index,DescType desiredType,
  1353.     KeyWord *key,AEDesc *theDesc); 
  1354. æDT OSErr myVariable = AEGetNthDesc((AEList) theList,(long) index,(DescType) desiredType,(
  1355.     KeyWord) * key,(AEDesc *) theDesc);
  1356. æC 
  1357.  
  1358. æKY AEGetKeyPtr
  1359. æFc AppleEvents.h
  1360. æT Function
  1361. æD 
  1362. pascal OSErr AEGetKeyPtr(AEList theList,KeyWord key,DescType desiredType,
  1363.     DescType *typeCode,Ptr dataPtr,long maxSize,long *actualSize); 
  1364. æDT OSErr myVariable = AEGetKeyPtr((AEList) theList,(KeyWord) key,(DescType) desiredType,(
  1365.     DescType) * typeCode,(Ptr) dataPtr,(long) maxSize,(long *) actualSize);
  1366. æC 
  1367.  
  1368. æKY AEGetKeyDesc
  1369. æFc AppleEvents.h
  1370. æT Function
  1371. æD 
  1372. pascal OSErr AEGetKeyDesc(AEList theList,KeyWord key,DescType desiredType,
  1373.     AEDesc *theDesc); 
  1374. æDT OSErr myVariable = AEGetKeyDesc((AEList) theList,(KeyWord) key,(DescType) desiredType,(
  1375.     AEDesc) * theDesc);
  1376. æC 
  1377.  
  1378. æKY AEGetArray
  1379. æFc AppleEvents.h
  1380. æT Function
  1381. æD 
  1382. pascal OSErr AEGetArray(AEList theList,AEArrayType arrayType,Ptr arrayPtr,
  1383.     long bufSize,DescType *elemType,long *elemSize,long *itemCount); 
  1384. æDT OSErr myVariable = AEGetArray((AEList) theList,(AEArrayType) arrayType,(Ptr) arrayPtr,()
  1385.     long bufSize,(DescType *) elemType,(long *) elemSize,(long *) itemCount);
  1386. æC 
  1387.  
  1388. æKY AEPutArray
  1389. æFc AppleEvents.h
  1390. æT Function
  1391. æD 
  1392. pascal OSErr AEPutArray(AEList theList,AEArrayType arrayType,Ptr arrayPtr,
  1393.     DescType elemType,long elemSize,long itemCount); 
  1394. æDT OSErr myVariable = AEPutArray((AEList) theList,(AEArrayType) arrayType,(Ptr) arrayPtr,()
  1395.     DescType elemType,(long) elemSize,(long) itemCount);
  1396. æC 
  1397.  
  1398. æKY AEDeleteIndex
  1399. æFc AppleEvents.h
  1400. æT Function
  1401. æD 
  1402. pascal OSErr AEDeleteIndex(AEList theList,long index); 
  1403. æDT OSErr myVariable = AEDeleteIndex((AEList) theList,(long) index);
  1404. æC 
  1405.  
  1406. æKY AEDeleteKey
  1407. æFc AppleEvents.h
  1408. æT Function
  1409. æD 
  1410. pascal OSErr AEDeleteKey(AEList theList,KeyWord key); 
  1411. æDT OSErr myVariable = AEDeleteKey((AEList) theList,(KeyWord) key);
  1412. æC 
  1413.  
  1414. æKY AECoerceDesc
  1415. æFc AppleEvents.h
  1416. æT Function
  1417. æD 
  1418. pascal OSErr AECoerceDesc(const AEDesc *desc,DescType toType,AEDesc *result); 
  1419. æDT OSErr myVariable = AECoerceDesc((const AEDesc *) desc,(DescType) toType,(AEDesc *) result);
  1420. æC 
  1421.  
  1422. æKY AEDisposeAEList
  1423. æFc AppleEvents.h
  1424. æT Function
  1425. æD 
  1426. pascal void AEDisposeAEList(AEList theArg); 
  1427. æDT 
  1428. AEDisposeAEList((AEList) theArg);
  1429. æC 
  1430.  
  1431. æKY AEDisposeAEDesc
  1432. æFc AppleEvents.h
  1433. æT Function
  1434. æD 
  1435. pascal void AEDisposeAEDesc(const AEDesc *theArg); 
  1436. æDT 
  1437. AEDisposeAEDesc((const AEDesc *) theArg);
  1438. æC 
  1439.  
  1440. æKY AECreateAevt
  1441. æFc AppleEvents.h
  1442. æT Function
  1443. æD 
  1444. pascal OSErr AECreateAevt(EventClass theEventClass,EventID theEventID,AEAdress target,
  1445.     long theRefCon,AEList *result); 
  1446. æDT OSErr myVariable = AECreateAevt((EventClass) theEventClass,(EventID) theEventID,(AEAdress) target,()
  1447.     long theRefCon,(AEList *) result);
  1448. æC 
  1449.  
  1450. æKY AEGetEventClassAndID
  1451. æFc AppleEvents.h
  1452. æT Function
  1453. æD /*  Extract the event class and id from the specified message  */
  1454. pascal void AEGetEventClassAndID(AEList theAevt,EventClass *theEventClass,
  1455.     EventID *theEventID); 
  1456. æDT /*  Extract the event class and id from the specified message  */
  1457. pascal void myVariable = AEGetEventClassAndID((AEList) theAevt,(EventClass *) theEventClass,(
  1458.     EventID) * theEventID);
  1459. æC 
  1460.  
  1461. æKY AEGetRefCon
  1462. æFc AppleEvents.h
  1463. æT Function
  1464. æD /*  Extract the event class and id from the specified message  */
  1465. pascal void AEGetRefCon(AEList theAevt,long *refCon); 
  1466. æDT /*  Extract the event class and id from the specified message  */
  1467. pascal void myVariable = AEGetRefCon((AEList) theAevt,(long *) refCon);
  1468. æC 
  1469.  
  1470. æKY AEGetAddress
  1471. æFc AppleEvents.h
  1472. æT Function
  1473. æD /*  Extract the address from the specified message  */
  1474. pascal void AEGetAddress(AEList theAevt,AEAddress *address); 
  1475. æDT /*  Extract the address from the specified message  */
  1476. pascal void myVariable = AEGetAddress((AEList) theAevt,(AEAddress *) address);
  1477. æC 
  1478.  
  1479. æKY AECreateList
  1480. æFc AppleEvents.h
  1481. æT Function
  1482. æD 
  1483. pascal OSErr AECreateList(Ptr factoringPtr,long factoredSize,Boolean isRecord,
  1484.     AEDesc *resultList); 
  1485. æDT OSErr myVariable = AECreateList((Ptr) factoringPtr,(long) factoredSize,(Boolean) isRecord,(
  1486.     AEDesc) * resultList);
  1487. æC 
  1488.  
  1489. æKY AECountListElems
  1490. æFc AppleEvents.h
  1491. æT Function
  1492. æD 
  1493. pascal long AECountListElems(AEList theList); 
  1494. æDT long myVariable = AECountListElems((AEList) theList);
  1495. æC 
  1496.  
  1497. æKY AESend
  1498. æFc AppleEvents.h
  1499. æT Function
  1500. æD 
  1501. pascal OSErr AESend(AEList theList,AEList *theReply,long sendMode,INTEGER sendPriority,
  1502.     long timeOut,ProcPtr idleProc); 
  1503. æDT OSErr myVariable = AESend((AEList) theList,(AEList *) theReply,(long) sendMode,(INTEGER) sendPriority,()
  1504.     long timeOut,(ProcPtr) idleProc);
  1505. æC 
  1506.  
  1507. æKY AEResetTimer
  1508. æFc AppleEvents.h
  1509. æT Function
  1510. æD /*  Convience routine.  Create and send a 'wait' message from the information in the reply.  */
  1511. pascal OSErr AEResetTimer(AEList reply); 
  1512. æDT /*  Convience routine.  Create and send a 'wait' message from the information in the reply.  */
  1513. pascal OSErr myVariable = AEResetTimer((AEList) reply);
  1514. æC 
  1515.  
  1516. æKY AESetAddressByPSN
  1517. æFc AppleEvents.h
  1518. æT Function
  1519. æD /*  Fill theAddressObject as receiverIDisPSN  */
  1520. pascal void AESetAddressByPSN(const ProcessSerialNumber *thePSN,AEAdress *theAddress); 
  1521. æDT /*  Fill theAddressObject as receiverIDisPSN  */
  1522. pascal void myVariable = AESetAddressByPSN((const ProcessSerialNumber *) thePSN,(AEAdress *) theAddress);
  1523. æC 
  1524.  
  1525. æKY AESetAddressBySignature
  1526. æFc AppleEvents.h
  1527. æT Function
  1528. æD /*  Fill theAddressObject as receiverIDisSignature  */
  1529. pascal void AESetAddressBySignature(OSType theSig,AEAddress *theAddress); 
  1530. æDT /*  Fill theAddressObject as receiverIDisSignature  */
  1531. pascal void myVariable = AESetAddressBySignature((OSType) theSig,(AEAddress *) theAddress);
  1532. æC 
  1533.  
  1534. æKY AESetAddressBySessionID
  1535. æFc AppleEvents.h
  1536. æT Function
  1537. æD /*  Fill theAddressObject as receiverIDisSessionID  */
  1538. pascal void AESetAddressBySessionID(long theSessionID,AEAddress *theAddress); 
  1539. æDT /*  Fill theAddressObject as receiverIDisSessionID  */
  1540. pascal void myVariable = AESetAddressBySessionID((long) theSessionID,(AEAddress *) theAddress);
  1541. æC 
  1542.  
  1543. æKY AESetAddressByTargetID
  1544. æFc AppleEvents.h
  1545. æT Function
  1546. æD /*  Fill theAddressObject as receiverIDisTargetID  */
  1547. pascal void AESetAddressByTargetID(const TargetID *theTargetID,AEAddress *theAddress); 
  1548. æDT /*  Fill theAddressObject as receiverIDisTargetID  */
  1549. pascal void myVariable = AESetAddressByTargetID((const TargetID *) theTargetID,(AEAddress *) theAddress);
  1550. æC 
  1551.  
  1552. æKY AEProcessAppleEvent
  1553. æFc AppleEvents.h
  1554. æT Function
  1555. æD 
  1556. pascal OSErr AEProcessAppleEvent(const EventRecord *eventRec); 
  1557. æDT OSErr myVariable = AEProcessAppleEvent((const EventRecord *) eventRec);
  1558. æC 
  1559.  
  1560. æKY AEGetDispatchTableRsrc
  1561. æFc AppleEvents.h
  1562. æT Function
  1563. æD /*  Load an event table from a 'AEDF' resource.  This of course will only be    of use to applications using a general dispatch routine rather than doing a direct dispatch to a handler.  */
  1564. pascal OSErr AEGetDispatchTableRsrc(INTEGER tableID); 
  1565. æDT /*  Load an event table from a 'AEDF' resource.  This of course will only be    of use to applications using a general dispatch routine rather than doing a direct dispatch to a handler.  */
  1566. pascal OSErr myVariable = AEGetDispatchTableRsrc((INTEGER) tableID);
  1567. æC 
  1568.  
  1569. æKY AECreateDispatchTable
  1570. æFc AppleEvents.h
  1571. æT Function
  1572. æD /*  Create an event table with one memory manager call for the number of events specified.  If more events are added to the table with AESetupEventTable, the table will be grown automatically.  */
  1573. pascal OSErr AECreateDispatchTable(INTEGER numEntries); 
  1574. æDT /*  Create an event table with one memory manager call for the number of events specified.  If more events are added to the table with AESetupEventTable, the table will be grown automatically.  */
  1575. pascal OSErr myVariable = AECreateDispatchTable((INTEGER) numEntries);
  1576. æC 
  1577.  
  1578. æKY AEAddEvtToTable
  1579. æFc AppleEvents.h
  1580. æT Function
  1581. æD /*  Add a single event to the table, expanding if necessary.  */
  1582. pascal OSErr AEAddEvtToTable(EventClass theEventClass,EventID theEventID,
  1583.     long value); 
  1584. æDT /*  Add a single event to the table, expanding if necessary.  */
  1585. pascal OSErr myVariable = AEAddEvtToTable((EventClass) theEventClass,(EventID) theEventID,()
  1586.     long value);
  1587. æC 
  1588.  
  1589. æKY AEGetTableEntry
  1590. æFc AppleEvents.h
  1591. æT Function
  1592. æD /*  returns the value of the specified event in theValue. kAEEventNotFound if not found.  */
  1593. pascal OSErr AEGetTableEntry(EventClass theEventClass,EventID theEventID,
  1594.     long *theValue); 
  1595. æDT /*  returns the value of the specified event in theValue. kAEEventNotFound if not found.  */
  1596. pascal OSErr myVariable = AEGetTableEntry((EventClass) theEventClass,(EventID) theEventID,(
  1597.     long) * theValue);
  1598. æC 
  1599.  
  1600. æKY AEInteractWithUser
  1601. æFc AppleEvents.h
  1602. æT Function
  1603. æD 
  1604. pascal OSErr AEInteractWithUser(long timeOut,QElemPtr nmReqPtr); 
  1605. æDT OSErr myVariable = AEInteractWithUser((long) timeOut,(QElemPtr) nmReqPtr);
  1606. æC 
  1607.  
  1608. æKY AEGetInteractLevel
  1609. æFc AppleEvents.h
  1610. æT Function
  1611. æD /*  returns kAENeverInteract, kAECanInteract or kAEAlwaysInteract  */
  1612. pascal INTEGER AEGetInteractLevel(AEList theAevt); 
  1613. æDT /*  returns kAENeverInteract, kAECanInteract or kAEAlwaysInteract  */
  1614. pascal INTEGER myVariable = AEGetInteractLevel((AEList) theAevt);
  1615. æC 
  1616.  
  1617. æKY AEInteractionAllowed
  1618. æFc AppleEvents.h
  1619. æT Function
  1620. æD 
  1621. pascal AEInteractAllowed AEInteractionAllowed(AEInteractAllowed theLevel); 
  1622. æDT AEInteractAllowed myVariable = AEInteractionAllowed((AEInteractAllowed) theLevel);
  1623. æC 
  1624.  
  1625. æKY AEWhichAevt
  1626. æFc AppleEvents.h
  1627. æT Function
  1628. æD 
  1629. pascal AEList AEWhichAevt(void); 
  1630. æDT AEList myVariable = AEWhichAevt()(void);
  1631. æC 
  1632.  
  1633.  
  1634. æKY AppleTalk.h
  1635. æKL AFPCommand
  1636. ASPAbortOS
  1637. ASPCloseAll
  1638. ASPCloseSession
  1639. ASPGetParms
  1640. ASPGetStatus
  1641. ASPOpenSession
  1642. ASPUserCommand
  1643. ASPUserWrite
  1644. ATPAddRsp
  1645. ATPCloseSocket
  1646. ATPGetRequest
  1647. ATPLoad
  1648. ATPOpenSocket
  1649. ATPReqCancel
  1650. ATPRequest
  1651. ATPResponse
  1652. ATPRspCancel
  1653. ATPSndRequest
  1654. ATPSndRsp
  1655. ATPUnload
  1656. BuildBDS
  1657. BuildDDPwds
  1658. BuildLAPwds
  1659. DDPCloseSocket
  1660. DDPOpenSocket
  1661. DDPRdCancel
  1662. DDPRead
  1663. DDPWrite
  1664. GetBridgeAddress
  1665. GetLocalZones
  1666. GetMyZone
  1667. GetNodeAddress
  1668. GetZoneList
  1669. IsATPOpen
  1670. IsMPPOpen
  1671. LAPCloseProtocol
  1672. LAPOpenProtocol
  1673. LAPRdCancel
  1674. LAPRead
  1675. LAPWrite
  1676. MPPClose
  1677. MPPOpen
  1678. NBPConfirm
  1679. NBPExtract
  1680. NBPLoad
  1681. NBPLookup
  1682. NBPRegister
  1683. NBPRemove
  1684. NBPSetEntity
  1685. NBPSetNTE
  1686. NBPUnload
  1687. OpenXPP
  1688. PAddResponse
  1689. PATalkClosePrep
  1690. PAttachPH
  1691. PCancelATalkClosePrep
  1692. PCloseATPSkt
  1693. PCloseSkt
  1694. PConfirmName
  1695. PDetachPH
  1696. PGetAppleTalkInfo
  1697. PGetRequest
  1698. PKillAllGetReq
  1699. PKillGetReq
  1700. PKillNBP
  1701. PKillSendReq
  1702. PLookupName
  1703. PNSendRequest
  1704. POpenATPSkt
  1705. POpenSkt
  1706. PRegisterName
  1707. PRelRspCB
  1708. PRelTCB
  1709. PRemoveName
  1710. PSendRequest
  1711. PSendResponse
  1712. PSetSelfSend
  1713. PWriteDDP
  1714. PWriteLAP
  1715. RemoveHdlBlocks
  1716.  
  1717. .
  1718. ABByte
  1719. ABCallType
  1720. ABProtoType
  1721. AddrBlock
  1722. afpAddAPPL
  1723. afpAddCmt
  1724. afpAddIcon
  1725. afpByteRangeLock
  1726. AFPCommandBlock
  1727. afpContLogin
  1728. afpCopyFile
  1729. afpDelete
  1730. afpDirClose
  1731. afpDirCreate
  1732. afpDTClose
  1733. afpDTOpen
  1734. afpEnumerate
  1735. afpFileCreate
  1736. afpFlush
  1737. afpForkClose
  1738. afpForkFlush
  1739. afpGetAPPL
  1740. afpGetCmt
  1741. afpGetDirParms
  1742. afpGetFileParms
  1743. afpGetFlDrParms
  1744. afpGetForkParms
  1745. afpGetIcon
  1746. afpGetSInfo
  1747. afpGetSParms
  1748. afpGetVolParms
  1749. afpGtIcnInfo
  1750. afpLogin
  1751. AFPLoginPrm
  1752. afpLogout
  1753. afpMapID
  1754. afpMapName
  1755. afpMove
  1756. afpOpenDir
  1757. afpOpenFork
  1758. afpOpenVol
  1759. afpRead
  1760. afpRename
  1761. afpRmvAPPL
  1762. afpRmvCmt
  1763. afpSetDirParms
  1764. afpSetFileParms
  1765. afpSetFlDrParms
  1766. afpSetForkParms
  1767. afpSetVolParms
  1768. afpVolClose
  1769. afpWrite
  1770. ASPAbortPrm
  1771. ASPGetparmsBlk
  1772. ASPOpenPrm
  1773. ASPOpenPrmPtr
  1774. ATATPRec
  1775. ATATPRecHandle
  1776. ATATPRecPtr
  1777. ATDDPRec
  1778. ATDDPRecHandle
  1779. ATDDPRecPtr
  1780. ATLAPRec
  1781. ATLAPRecHandle
  1782. ATLAPRecPtr
  1783. ATNBPRec
  1784. ATNBPRecHandle
  1785. ATNBPRecPtr
  1786. ATPaddrBlock
  1787. ATPaKillQEl
  1788. ATPatpFlags
  1789. ATPatpSocket
  1790. ATPbdsPointer
  1791. ATPbdsSize
  1792. ATPbitMap
  1793. ATPcsCode
  1794. atpEOMvalue
  1795. ATPioCompletion
  1796. ATPioRefNum
  1797. ATPioResult
  1798. ATPmisc1
  1799. ATPmisc2
  1800. ATPnumOfBuffs
  1801. ATPnumOfResps
  1802. ATPParamBlock
  1803. ATPparms
  1804. ATPPBPtr
  1805. atpProto
  1806. ATPreqLength
  1807. ATPreqPointer
  1808. ATPreqTID
  1809. ATPretryCount
  1810. ATPrspNum
  1811. atpSendChkvalue
  1812. atpSize
  1813. atpSTSvalue
  1814. atpTIDValidvalue
  1815. ATPtimeOutVal
  1816. ATPtransID
  1817. ATPuserData
  1818. atpXOvalue
  1819. ATQEntry
  1820. BDSElement
  1821. BitMapType
  1822. DDPchecksumFlag
  1823. DDPlistener
  1824. DDPparms
  1825. ddpProto
  1826. ddpSize
  1827. DDPsocket
  1828. DDPwdsPointer
  1829. EntityName
  1830. EntityPtr
  1831. Killparms
  1832. LAPAdrBlock
  1833. LAPhandler
  1834. LAPMgrCall
  1835. LAPMgrPtr
  1836. LAPparms
  1837. lapProto
  1838. LAPprotType
  1839. lapSize
  1840. LAPwdsPointer
  1841. MOREATPHeader
  1842. MPPATPHeader
  1843. MPPcsCode
  1844. MPPioCompletion
  1845. MPPioRefNum
  1846. MPPioResult
  1847. MPPParamBlock
  1848. MPPparms
  1849. MPPPBPtr
  1850. NamesTableEntry
  1851. NBPconfirmAddr
  1852. NBPcount
  1853. NBPentityPtr
  1854. NBPinterval
  1855. NBPKillparms
  1856. NBPmaxToGet
  1857. NBPnewSocket
  1858. NBPnKillQEl
  1859. NBPntQElPtr
  1860. NBPnumGotten
  1861. NBPparms
  1862. nbpProto
  1863. NBPretBuffPtr
  1864. NBPretBuffSize
  1865. nbpSize
  1866. NBPverifyFlag
  1867. NTElement
  1868. RetransType
  1869. scbMemSize
  1870. SendReqparms
  1871. SetSelfparms
  1872. Str32
  1873. tATPAddRsp
  1874. tATPGetRequest
  1875. tATPRequest
  1876. tATPResponse
  1877. tATPSdRsp
  1878. tATPSndRequest
  1879. tDDPRead
  1880. tDDPWrite
  1881. tLAPRead
  1882. tLAPWrite
  1883. tNBPConfirm
  1884. tNBPLookup
  1885. tNBPRegister
  1886. WDSElement
  1887. xppFlagClr
  1888. xppFlagSet
  1889. xppLoadedBit
  1890. XPPParamBlock
  1891. XPPParmBlkPtr
  1892. XPPPBHeader
  1893. XPPPrmBlk
  1894. xppRefNum
  1895. xppUnitNum
  1896.  
  1897. æKY afpByteRangeLock
  1898. æFc AppleTalk.h
  1899. æT #define
  1900. æD #define afpByteRangeLock 1 /*AFPCall command codes*/
  1901. æC 
  1902.  
  1903. æKY afpVolClose
  1904. æFc AppleTalk.h
  1905. æT #define
  1906. æD #define afpVolClose 2 /*AFPCall command codes*/
  1907. æC 
  1908.  
  1909. æKY afpDirClose
  1910. æFc AppleTalk.h
  1911. æT #define
  1912. æD #define afpDirClose 3 /*AFPCall command codes*/
  1913. æC 
  1914.  
  1915. æKY afpForkClose
  1916. æFc AppleTalk.h
  1917. æT #define
  1918. æD #define afpForkClose 4 /*AFPCall command codes*/
  1919. æC 
  1920.  
  1921. æKY afpCopyFile
  1922. æFc AppleTalk.h
  1923. æT #define
  1924. æD #define afpCopyFile 5 /*AFPCall command codes*/
  1925. æC 
  1926.  
  1927. æKY afpDirCreate
  1928. æFc AppleTalk.h
  1929. æT #define
  1930. æD #define afpDirCreate 6 /*AFPCall command codes*/
  1931. æC 
  1932.  
  1933. æKY afpFileCreate
  1934. æFc AppleTalk.h
  1935. æT #define
  1936. æD #define afpFileCreate 7 /*AFPCall command codes*/
  1937. æC 
  1938.  
  1939. æKY afpDelete
  1940. æFc AppleTalk.h
  1941. æT #define
  1942. æD #define afpDelete 8 /*AFPCall command codes*/
  1943. æC 
  1944.  
  1945. æKY afpEnumerate
  1946. æFc AppleTalk.h
  1947. æT #define
  1948. æD #define afpEnumerate 9 /*AFPCall command codes*/
  1949. æC 
  1950.  
  1951. æKY afpFlush
  1952. æFc AppleTalk.h
  1953. æT #define
  1954. æD #define afpFlush 10 /*AFPCall command codes*/
  1955. æC 
  1956.  
  1957. æKY afpForkFlush
  1958. æFc AppleTalk.h
  1959. æT #define
  1960. æD #define afpForkFlush 11 /*AFPCall command codes*/
  1961. æC 
  1962.  
  1963. æKY afpGetDirParms
  1964. æFc AppleTalk.h
  1965. æT #define
  1966. æD #define afpGetDirParms 12 /*AFPCall command codes*/
  1967. æC 
  1968.  
  1969. æKY afpGetFileParms
  1970. æFc AppleTalk.h
  1971. æT #define
  1972. æD #define afpGetFileParms 13 /*AFPCall command codes*/
  1973. æC 
  1974.  
  1975. æKY afpGetForkParms
  1976. æFc AppleTalk.h
  1977. æT #define
  1978. æD #define afpGetForkParms 14 /*AFPCall command codes*/
  1979. æC 
  1980.  
  1981. æKY afpGetSInfo
  1982. æFc AppleTalk.h
  1983. æT #define
  1984. æD #define afpGetSInfo 15 /*AFPCall command codes*/
  1985. æC 
  1986.  
  1987. æKY afpGetSParms
  1988. æFc AppleTalk.h
  1989. æT #define
  1990. æD #define afpGetSParms 16 /*AFPCall command codes*/
  1991. æC 
  1992.  
  1993. æKY afpGetVolParms
  1994. æFc AppleTalk.h
  1995. æT #define
  1996. æD #define afpGetVolParms 17 /*AFPCall command codes*/
  1997. æC 
  1998.  
  1999. æKY afpLogin
  2000. æFc AppleTalk.h
  2001. æT #define
  2002. æD #define afpLogin 18 /*AFPCall command codes*/
  2003. æC 
  2004.  
  2005. æKY afpContLogin
  2006. æFc AppleTalk.h
  2007. æT #define
  2008. æD #define afpContLogin 19 /*AFPCall command codes*/
  2009. æC 
  2010.  
  2011. æKY afpLogout
  2012. æFc AppleTalk.h
  2013. æT #define
  2014. æD #define afpLogout 20 /*AFPCall command codes*/
  2015. æC 
  2016.  
  2017. æKY afpMapID
  2018. æFc AppleTalk.h
  2019. æT #define
  2020. æD #define afpMapID 21 /*AFPCall command codes*/
  2021. æC 
  2022.  
  2023. æKY afpMapName
  2024. æFc AppleTalk.h
  2025. æT #define
  2026. æD #define afpMapName 22 /*AFPCall command codes*/
  2027. æC 
  2028.  
  2029. æKY afpMove
  2030. æFc AppleTalk.h
  2031. æT #define
  2032. æD #define afpMove 23 /*AFPCall command codes*/
  2033. æC 
  2034.  
  2035. æKY afpOpenVol
  2036. æFc AppleTalk.h
  2037. æT #define
  2038. æD #define afpOpenVol 24 /*AFPCall command codes*/
  2039. æC 
  2040.  
  2041. æKY afpOpenDir
  2042. æFc AppleTalk.h
  2043. æT #define
  2044. æD #define afpOpenDir 25 /*AFPCall command codes*/
  2045. æC 
  2046.  
  2047. æKY afpOpenFork
  2048. æFc AppleTalk.h
  2049. æT #define
  2050. æD #define afpOpenFork 26 /*AFPCall command codes*/
  2051. æC 
  2052.  
  2053. æKY afpRead
  2054. æFc AppleTalk.h
  2055. æT #define
  2056. æD #define afpRead 27 /*AFPCall command codes*/
  2057. æC 
  2058.  
  2059. æKY afpRename
  2060. æFc AppleTalk.h
  2061. æT #define
  2062. æD #define afpRename 28 /*AFPCall command codes*/
  2063. æC 
  2064.  
  2065. æKY afpSetDirParms
  2066. æFc AppleTalk.h
  2067. æT #define
  2068. æD #define afpSetDirParms 29 /*AFPCall command codes*/
  2069. æC 
  2070.  
  2071. æKY afpSetFileParms
  2072. æFc AppleTalk.h
  2073. æT #define
  2074. æD #define afpSetFileParms 30 /*AFPCall command codes*/
  2075. æC 
  2076.  
  2077. æKY afpSetForkParms
  2078. æFc AppleTalk.h
  2079. æT #define
  2080. æD #define afpSetForkParms 31 /*AFPCall command codes*/
  2081. æC 
  2082.  
  2083. æKY afpSetVolParms
  2084. æFc AppleTalk.h
  2085. æT #define
  2086. æD #define afpSetVolParms 32 /*AFPCall command codes*/
  2087. æC 
  2088.  
  2089. æKY afpWrite
  2090. æFc AppleTalk.h
  2091. æT #define
  2092. æD #define afpWrite 33 /*AFPCall command codes*/
  2093. æC 
  2094.  
  2095. æKY afpGetFlDrParms
  2096. æFc AppleTalk.h
  2097. æT #define
  2098. æD #define afpGetFlDrParms 34 /*AFPCall command codes*/
  2099. æC 
  2100.  
  2101. æKY afpSetFlDrParms
  2102. æFc AppleTalk.h
  2103. æT #define
  2104. æD #define afpSetFlDrParms 35 /*AFPCall command codes*/
  2105. æC 
  2106.  
  2107. æKY afpDTOpen
  2108. æFc AppleTalk.h
  2109. æT #define
  2110. æD #define afpDTOpen 48 /*AFPCall command codes*/
  2111. æC 
  2112.  
  2113. æKY afpDTClose
  2114. æFc AppleTalk.h
  2115. æT #define
  2116. æD #define afpDTClose 49 /*AFPCall command codes*/
  2117. æC 
  2118.  
  2119. æKY afpGetIcon
  2120. æFc AppleTalk.h
  2121. æT #define
  2122. æD #define afpGetIcon 51 /*AFPCall command codes*/
  2123. æC 
  2124.  
  2125. æKY afpGtIcnInfo
  2126. æFc AppleTalk.h
  2127. æT #define
  2128. æD #define afpGtIcnInfo 52 /*AFPCall command codes*/
  2129. æC 
  2130.  
  2131. æKY afpAddAPPL
  2132. æFc AppleTalk.h
  2133. æT #define
  2134. æD #define afpAddAPPL 53 /*AFPCall command codes*/
  2135. æC 
  2136.  
  2137. æKY afpRmvAPPL
  2138. æFc AppleTalk.h
  2139. æT #define
  2140. æD #define afpRmvAPPL 54 /*AFPCall command codes*/
  2141. æC 
  2142.  
  2143. æKY afpGetAPPL
  2144. æFc AppleTalk.h
  2145. æT #define
  2146. æD #define afpGetAPPL 55 /*AFPCall command codes*/
  2147. æC 
  2148.  
  2149. æKY afpAddCmt
  2150. æFc AppleTalk.h
  2151. æT #define
  2152. æD #define afpAddCmt 56 /*AFPCall command codes*/
  2153. æC 
  2154.  
  2155. æKY afpRmvCmt
  2156. æFc AppleTalk.h
  2157. æT #define
  2158. æD #define afpRmvCmt 57 /*AFPCall command codes*/
  2159. æC 
  2160.  
  2161. æKY afpGetCmt
  2162. æFc AppleTalk.h
  2163. æT #define
  2164. æD #define afpGetCmt 58 /*AFPCall command codes*/
  2165. æC 
  2166.  
  2167. æKY afpAddIcon
  2168. æFc AppleTalk.h
  2169. æT #define
  2170. æD #define afpAddIcon 192 /*Special code for ASP Write commands*/
  2171. æC 
  2172.  
  2173. æKY xppLoadedBit
  2174. æFc AppleTalk.h
  2175. æT #define
  2176. æD #define xppLoadedBit 5 /* XPP bit in PortBUse */
  2177. æC 
  2178.  
  2179. æKY xppUnitNum
  2180. æFc AppleTalk.h
  2181. æT #define
  2182. æD #define xppUnitNum 40 /*Unit number for XPP (old ROMs) */
  2183. æC 
  2184.  
  2185. æKY xppRefNum
  2186. æFc AppleTalk.h
  2187. æT #define
  2188. æD #define xppRefNum -41 /*.XPP reference number */
  2189. æC 
  2190.  
  2191. æKY scbMemSize
  2192. æFc AppleTalk.h
  2193. æT #define
  2194. æD #define scbMemSize 192 /*Size of memory for SCB */
  2195. æC 
  2196.  
  2197. æKY xppFlagClr
  2198. æFc AppleTalk.h
  2199. æT #define
  2200. æD #define xppFlagClr 0 /*Cs for AFPCommandBlock */
  2201. æC 
  2202.  
  2203. æKY xppFlagSet
  2204. æFc AppleTalk.h
  2205. æT #define
  2206. æD #define xppFlagSet 128 /*StartEndFlag & NewLineFlag fields. */
  2207. æC 
  2208.  
  2209. æKY lapSize
  2210. æFc AppleTalk.h
  2211. æT #define
  2212. æD #define lapSize 20
  2213. æC 
  2214.  
  2215. æKY ddpSize
  2216. æFc AppleTalk.h
  2217. æT #define
  2218. æD #define ddpSize 26
  2219. æC 
  2220.  
  2221. æKY nbpSize
  2222. æFc AppleTalk.h
  2223. æT #define
  2224. æD #define nbpSize 26
  2225. æC 
  2226.  
  2227. æKY atpSize
  2228. æFc AppleTalk.h
  2229. æT #define
  2230. æD #define atpSize 56
  2231. æC 
  2232.  
  2233. æKY MPPioCompletion
  2234. æFc AppleTalk.h
  2235. æT #define
  2236. æD #define MPPioCompletion MPP.ioCompletion
  2237. æC 
  2238.  
  2239. æKY MPPioResult
  2240. æFc AppleTalk.h
  2241. æT #define
  2242. æD #define MPPioResult MPP.ioResult
  2243. æC 
  2244.  
  2245. æKY MPPioRefNum
  2246. æFc AppleTalk.h
  2247. æT #define
  2248. æD #define MPPioRefNum MPP.ioRefNum
  2249. æC 
  2250.  
  2251. æKY MPPcsCode
  2252. æFc AppleTalk.h
  2253. æT #define
  2254. æD #define MPPcsCode MPP.csCode
  2255. æC 
  2256.  
  2257. æKY LAPprotType
  2258. æFc AppleTalk.h
  2259. æT #define
  2260. æD #define LAPprotType LAP.protType
  2261. æC 
  2262.  
  2263. æKY LAPwdsPointer
  2264. æFc AppleTalk.h
  2265. æT #define
  2266. æD #define LAPwdsPointer LAP.LAPptrs.wdsPointer
  2267. æC 
  2268.  
  2269. æKY LAPhandler
  2270. æFc AppleTalk.h
  2271. æT #define
  2272. æD #define LAPhandler LAP.LAPptrs.handler
  2273. æC 
  2274.  
  2275. æKY DDPsocket
  2276. æFc AppleTalk.h
  2277. æT #define
  2278. æD #define DDPsocket DDP.socket
  2279. æC 
  2280.  
  2281. æKY DDPchecksumFlag
  2282. æFc AppleTalk.h
  2283. æT #define
  2284. æD #define DDPchecksumFlag DDP.checksumFlag
  2285. æC 
  2286.  
  2287. æKY DDPwdsPointer
  2288. æFc AppleTalk.h
  2289. æT #define
  2290. æD #define DDPwdsPointer DDP.DDPptrs.wdsPointer
  2291. æC 
  2292.  
  2293. æKY DDPlistener
  2294. æFc AppleTalk.h
  2295. æT #define
  2296. æD #define DDPlistener DDP.DDPptrs.listener
  2297. æC 
  2298.  
  2299. æKY NBPinterval
  2300. æFc AppleTalk.h
  2301. æT #define
  2302. æD #define NBPinterval NBP.interval
  2303. æC 
  2304.  
  2305. æKY NBPcount
  2306. æFc AppleTalk.h
  2307. æT #define
  2308. æD #define NBPcount NBP.count
  2309. æC 
  2310.  
  2311. æKY NBPntQElPtr
  2312. æFc AppleTalk.h
  2313. æT #define
  2314. æD #define NBPntQElPtr NBP.NBPPtrs.ntQElPtr
  2315. æC 
  2316.  
  2317. æKY NBPentityPtr
  2318. æFc AppleTalk.h
  2319. æT #define
  2320. æD #define NBPentityPtr NBP.NBPPtrs.entityPtr
  2321. æC 
  2322.  
  2323. æKY NBPverifyFlag
  2324. æFc AppleTalk.h
  2325. æT #define
  2326. æD #define NBPverifyFlag NBP.parm.verifyFlag
  2327. æC 
  2328.  
  2329. æKY NBPretBuffPtr
  2330. æFc AppleTalk.h
  2331. æT #define
  2332. æD #define NBPretBuffPtr NBP.parm.Lookup.retBuffPtr
  2333. æC 
  2334.  
  2335. æKY NBPretBuffSize
  2336. æFc AppleTalk.h
  2337. æT #define
  2338. æD #define NBPretBuffSize NBP.parm.Lookup.retBuffSize
  2339. æC 
  2340.  
  2341. æKY NBPmaxToGet
  2342. æFc AppleTalk.h
  2343. æT #define
  2344. æD #define NBPmaxToGet NBP.parm.Lookup.maxToGet
  2345. æC 
  2346.  
  2347. æKY NBPnumGotten
  2348. æFc AppleTalk.h
  2349. æT #define
  2350. æD #define NBPnumGotten NBP.parm.Lookup.numGotten
  2351. æC 
  2352.  
  2353. æKY NBPconfirmAddr
  2354. æFc AppleTalk.h
  2355. æT #define
  2356. æD #define NBPconfirmAddr NBP.parm.Confirm.confirmAddr
  2357. æC 
  2358.  
  2359. æKY NBPnKillQEl
  2360. æFc AppleTalk.h
  2361. æT #define
  2362. æD #define NBPnKillQEl NBPKILL.nKillQEl
  2363. æC 
  2364.  
  2365. æKY NBPnewSocket
  2366. æFc AppleTalk.h
  2367. æT #define
  2368. æD #define NBPnewSocket NBP.parm.Confirm.newSocket
  2369. æC 
  2370.  
  2371. æKY ATPioCompletion
  2372. æFc AppleTalk.h
  2373. æT #define
  2374. æD #define ATPioCompletion ATP.ioCompletion
  2375. æC 
  2376.  
  2377. æKY ATPioResult
  2378. æFc AppleTalk.h
  2379. æT #define
  2380. æD #define ATPioResult ATP.ioResult
  2381. æC 
  2382.  
  2383. æKY ATPuserData
  2384. æFc AppleTalk.h
  2385. æT #define
  2386. æD #define ATPuserData ATP.userData
  2387. æC 
  2388.  
  2389. æKY ATPreqTID
  2390. æFc AppleTalk.h
  2391. æT #define
  2392. æD #define ATPreqTID ATP.reqTID
  2393. æC 
  2394.  
  2395. æKY ATPioRefNum
  2396. æFc AppleTalk.h
  2397. æT #define
  2398. æD #define ATPioRefNum ATP.ioRefNum
  2399. æC 
  2400.  
  2401. æKY ATPcsCode
  2402. æFc AppleTalk.h
  2403. æT #define
  2404. æD #define ATPcsCode ATP.csCode
  2405. æC 
  2406.  
  2407. æKY ATPatpSocket
  2408. æFc AppleTalk.h
  2409. æT #define
  2410. æD #define ATPatpSocket ATP.atpSocket
  2411. æC 
  2412.  
  2413. æKY ATPatpFlags
  2414. æFc AppleTalk.h
  2415. æT #define
  2416. æD #define ATPatpFlags ATP.atpFlags
  2417. æC 
  2418.  
  2419. æKY ATPaddrBlock
  2420. æFc AppleTalk.h
  2421. æT #define
  2422. æD #define ATPaddrBlock ATP.addrBlock
  2423. æC 
  2424.  
  2425. æKY ATPreqLength
  2426. æFc AppleTalk.h
  2427. æT #define
  2428. æD #define ATPreqLength ATP.reqLength
  2429. æC 
  2430.  
  2431. æKY ATPreqPointer
  2432. æFc AppleTalk.h
  2433. æT #define
  2434. æD #define ATPreqPointer ATP.reqPointer
  2435. æC 
  2436.  
  2437. æKY ATPbdsPointer
  2438. æFc AppleTalk.h
  2439. æT #define
  2440. æD #define ATPbdsPointer ATP.bdsPointer
  2441. æC 
  2442.  
  2443. æKY ATPtimeOutVal
  2444. æFc AppleTalk.h
  2445. æT #define
  2446. æD #define ATPtimeOutVal SREQ.timeOutVal
  2447. æC 
  2448.  
  2449. æKY ATPnumOfResps
  2450. æFc AppleTalk.h
  2451. æT #define
  2452. æD #define ATPnumOfResps SREQ.numOfResps
  2453. æC 
  2454.  
  2455. æKY ATPretryCount
  2456. æFc AppleTalk.h
  2457. æT #define
  2458. æD #define ATPretryCount SREQ.retryCount
  2459. æC 
  2460.  
  2461. æKY ATPnumOfBuffs
  2462. æFc AppleTalk.h
  2463. æT #define
  2464. æD #define ATPnumOfBuffs OTH1.u0.numOfBuffs
  2465. æC 
  2466.  
  2467. æKY ATPbitMap
  2468. æFc AppleTalk.h
  2469. æT #define
  2470. æD #define ATPbitMap OTH1.u0.bitMap
  2471. æC 
  2472.  
  2473. æKY ATPrspNum
  2474. æFc AppleTalk.h
  2475. æT #define
  2476. æD #define ATPrspNum OTH1.u0.rspNum
  2477. æC 
  2478.  
  2479. æKY ATPbdsSize
  2480. æFc AppleTalk.h
  2481. æT #define
  2482. æD #define ATPbdsSize OTH2.bdsSize
  2483. æC 
  2484.  
  2485. æKY ATPtransID
  2486. æFc AppleTalk.h
  2487. æT #define
  2488. æD #define ATPtransID OTH2.transID
  2489. æC 
  2490.  
  2491. æKY ATPaKillQEl
  2492. æFc AppleTalk.h
  2493. æT #define
  2494. æD #define ATPaKillQEl KILL.aKillQEl
  2495. æC 
  2496.  
  2497. æKY atpXOvalue
  2498. æFc AppleTalk.h
  2499. æT #define
  2500. æD #define atpXOvalue 32 /*ATP exactly-once bit */
  2501. æC 
  2502.  
  2503. æKY atpEOMvalue
  2504. æFc AppleTalk.h
  2505. æT #define
  2506. æD #define atpEOMvalue 16 /*ATP End-Of-Message bit */
  2507. æC 
  2508.  
  2509. æKY atpSTSvalue
  2510. æFc AppleTalk.h
  2511. æT #define
  2512. æD #define atpSTSvalue 8 /*ATP Send-Transmission-Status bit */
  2513. æC 
  2514.  
  2515. æKY atpTIDValidvalue
  2516. æFc AppleTalk.h
  2517. æT #define
  2518. æD #define atpTIDValidvalue 2 /*ATP trans. ID valid bit */
  2519. æC 
  2520.  
  2521. æKY atpSendChkvalue
  2522. æFc AppleTalk.h
  2523. æT #define
  2524. æD #define atpSendChkvalue 1 /*ATP send checksum bit */
  2525. æC 
  2526.  
  2527. æKY LAPMgrPtr
  2528. æFc AppleTalk.h
  2529. æT #define
  2530. æD #define LAPMgrPtr 0xB18 /*Entry point for LAP Manager*/
  2531. æC 
  2532.  
  2533. æKY LAPMgrCall
  2534. æFc AppleTalk.h
  2535. æT #define
  2536. æD #define LAPMgrCall 2 /*Offset to LAP routines*/
  2537. æC 
  2538.  
  2539. æKY ABCallType
  2540. tLAPRead
  2541. tLAPWrite
  2542. tDDPRead
  2543. tDDPWrite
  2544. tNBPLookup
  2545. tNBPConfirm
  2546. tNBPRegister
  2547. tATPSndRequest
  2548. tATPGetRequest
  2549. tATPSdRsp
  2550. tATPAddRsp
  2551. tATPRequest
  2552. tATPResponse
  2553. æFc AppleTalk.h
  2554. æT enum
  2555. æD enum {tLAPRead,tLAPWrite,tDDPRead,tDDPWrite,tNBPLookup,tNBPConfirm,tNBPRegister,
  2556.     tATPSndRequest,tATPGetRequest,tATPSdRsp,tATPAddRsp,tATPRequest,tATPResponse};
  2557. typedef unsigned char ABCallType;
  2558. æC 
  2559.  
  2560. æKY ABProtoType
  2561. lapProto
  2562. ddpProto
  2563. nbpProto
  2564. atpProto
  2565. æFc AppleTalk.h
  2566. æT enum
  2567. æD enum {lapProto,ddpProto,nbpProto,atpProto};
  2568. typedef unsigned char ABProtoType;
  2569. æC 
  2570.  
  2571. æKY ABByte
  2572. .
  2573. æFc AppleTalk.h
  2574. æT typedef
  2575. æD typedef unsigned char ABByte;
  2576. æC 
  2577.  
  2578. æKY BitMapType
  2579. æFc AppleTalk.h
  2580. æT typedef
  2581. æD typedef char BitMapType;
  2582. æC 
  2583.  
  2584. æKY Str32
  2585. æFc AppleTalk.h
  2586. æT typedef
  2587. æD typedef char Str32[33];
  2588. æC 
  2589.  
  2590. æKY LAPAdrBlock
  2591. æFc AppleTalk.h
  2592. æT struct
  2593. æD struct LAPAdrBlock {
  2594.     unsigned char dstNodeID;
  2595.     unsigned char srcNodeID;
  2596.     ABByte lapProtType;
  2597. };
  2598.  
  2599. typedef struct LAPAdrBlock LAPAdrBlock;
  2600. æC 
  2601.  
  2602. æKY ATQEntry
  2603. æFc AppleTalk.h
  2604. æT struct
  2605. æD struct ATQEntry {
  2606.     QElemPtr qLink; /*next queue entry*/
  2607.     Integer qType; /*queue type*/
  2608.     ProcPtr CallAddr; /*Pointer to your routine*/
  2609. };
  2610.  
  2611. typedef struct ATQEntry ATQEntry;
  2612. typedef ATQEntry *ATQEntry;
  2613.  
  2614. æC 
  2615.  
  2616. æKY AddrBlock
  2617. æFc AppleTalk.h
  2618. æT struct
  2619. æD struct AddrBlock {
  2620.     short aNet;
  2621.     unsigned char aNode;
  2622.     unsigned char aSocket;
  2623. };
  2624.  
  2625. typedef struct AddrBlock AddrBlock;
  2626. æC 
  2627.  
  2628. æKY EntityName
  2629. EntityPtr
  2630. æFc AppleTalk.h
  2631. æT struct
  2632. æD struct EntityName {
  2633.     Str32 objStr;
  2634.     char pad1; /*Str32's aligned on even word boundries.*/
  2635.     Str32 typeStr;
  2636.     char pad2;
  2637.     Str32 zoneStr;
  2638.     char pad3;
  2639. };
  2640.  
  2641. typedef struct EntityName EntityName;
  2642. typedef EntityName *EntityPtr;
  2643.  
  2644. /* Real definition of EntityName is 3 PACKED strings of any length (32 is just an example). No
  2645. offests for Asm since each String address must be calculated by adding length byte to last string ptr. 
  2646. In Pascal, String(32) will be 34 bytes long since fields never start on an odd byte unless they are 
  2647. only a byte long. So this will generate correct looking interfaces for Pascal and C, but they will not 
  2648. be the same, which is OK since they are not used. */
  2649. æC \* Real definition of EntityName is 3 PACKED strings of any length (32 is just an 
  2650. example). No offsets for Asm since each String address must be calculated by adding 
  2651. length byte to last string ptr. 
  2652.  
  2653. In Pascal, String(32) will be 34 bytes long since fields never start on an odd byte 
  2654. unless they are only a byte long. So this will generate correct looking interfaces for 
  2655. Pascal and C, but they will not be the same, which is OK since they are not used. */
  2656.  
  2657. æKY RetransType
  2658. æFc AppleTalk.h
  2659. æT struct
  2660. æD struct RetransType {
  2661.     unsigned char retransInterval;
  2662.     unsigned char retransCount;
  2663. };
  2664.  
  2665. typedef struct RetransType RetransType;
  2666. æC 
  2667.  
  2668. æKY BDSElement
  2669. æFc AppleTalk.h
  2670. æT struct
  2671. æD struct BDSElement {
  2672.     short buffSize;
  2673.     Ptr buffPtr;
  2674.     short dataSize;
  2675.     long userBytes;
  2676. };
  2677.  
  2678. typedef struct BDSElement BDSElement;
  2679. typedef BDSElement BDSType[8];
  2680. typedef BDSType *BDSPtr;
  2681.  
  2682.  
  2683. æC 
  2684.  
  2685. æKY ATLAPRec
  2686. ATLAPRecPtr
  2687. ATLAPRecHandle
  2688. æFc AppleTalk.h
  2689. æT struct
  2690. æD struct ATLAPRec {
  2691.     ABCallType abOpcode;
  2692.     short abResult;
  2693.     long abUserReference;
  2694.     LAPAdrBlock lapAddress;
  2695.     short lapReqCount;
  2696.     short lapActCount;
  2697.     Ptr lapDataPtr;
  2698. };
  2699.  
  2700. typedef struct ATLAPRec ATLAPRec;
  2701. typedef ATLAPRec *ATLAPRecPtr, **ATLAPRecHandle;
  2702.  
  2703. æC 
  2704.  
  2705. æKY ATDDPRec
  2706. ATDDPRecPtr
  2707. ATDDPRecHandle
  2708. æFc AppleTalk.h
  2709. æT struct
  2710. æD struct ATDDPRec {
  2711.     ABCallType abOpcode;
  2712.     short abResult;
  2713.     long abUserReference;
  2714.     short ddpType;
  2715.     short ddpSocket;
  2716.     AddrBlock ddpAddress;
  2717.     short ddpReqCount;
  2718.     short ddpActCount;
  2719.     Ptr ddpDataPtr;
  2720.     short ddpNodeID;
  2721. };
  2722.  
  2723. typedef struct ATDDPRec ATDDPRec;
  2724. typedef ATDDPRec *ATDDPRecPtr, **ATDDPRecHandle;
  2725.  
  2726. æC 
  2727.  
  2728. æKY ATNBPRec
  2729. ATNBPRecPtr
  2730. ATNBPRecHandle
  2731. æFc AppleTalk.h
  2732. æT struct
  2733. æD struct ATNBPRec {
  2734.     ABCallType abOpcode;
  2735.     short abResult;
  2736.     long abUserReference;
  2737.     EntityPtr nbpEntityPtr;
  2738.     Ptr nbpBufPtr;
  2739.     short nbpBufSize;
  2740.     short nbpDataField;
  2741.     AddrBlock nbpAddress;
  2742.     RetransType nbpRetransmitInfo;
  2743. };
  2744.  
  2745. typedef struct ATNBPRec ATNBPRec;
  2746. typedef ATNBPRec *ATNBPRecPtr, **ATNBPRecHandle;
  2747.  
  2748. æC 
  2749.  
  2750. æKY ATATPRec
  2751. ATATPRecPtr
  2752. ATATPRecHandle
  2753. æFc AppleTalk.h
  2754. æT struct
  2755. æD struct ATATPRec {
  2756.     ABCallType abOpcode;
  2757.     short abResult;
  2758.     long abUserReference;
  2759.     short atpSocket;
  2760.     AddrBlock atpAddress;
  2761.     short atpReqCount;
  2762.     Ptr atpDataPtr;
  2763.     BDSPtr atpRspBDSPtr;
  2764.     BitMapType atpBitMap;
  2765.     short atpTransID;
  2766.     short atpActCount;
  2767.     long atpUserData;
  2768.     Boolean atpXO;
  2769.     Boolean atpEOM;
  2770.     short atpTimeOut;
  2771.     short atpRetries;
  2772.     short atpNumBufs;
  2773.     short atpNumRsp;
  2774.     short atpBDSSize;
  2775.     long atpRspUData;
  2776.     Ptr atpRspBuf;
  2777.     short atpRspSize;
  2778. };
  2779.  
  2780. typedef struct ATATPRec ATATPRec;
  2781. typedef ATATPRec *ATATPRecPtr, **ATATPRecHandle;
  2782.  
  2783. æC 
  2784.  
  2785. æKY AFPCommandBlock
  2786. æFc AppleTalk.h
  2787. æT struct
  2788. æD typedef struct {
  2789.     char cmdByte;
  2790.     char startEndFlag;
  2791.     short forkRefNum;
  2792.     long rwOffset;
  2793.     long reqCount;
  2794.     char newLineFlag;
  2795.     char newLineChar;
  2796. }AFPCommandBlock;
  2797.  
  2798. æC 
  2799.  
  2800. æKY XPPPBHeader
  2801. æFc AppleTalk.h
  2802. æT struct
  2803. æD #define XPPPBHeader \
  2804.     QElem *qLink;
  2805.     short qType;
  2806.     short ioTrap;
  2807.     Ptr ioCmdAddr;
  2808.     ProcPtr ioCompletion;
  2809.     OSErr ioResult;
  2810.     long cmdResult;
  2811.     short ioVRefNum;
  2812.     short ioRefNum;
  2813.     short csCode;
  2814.  
  2815.  
  2816. æC 
  2817.  
  2818. æKY XPPPrmBlk
  2819. æFc AppleTalk.h
  2820. æT struct
  2821. æD typedef struct {
  2822.     XPPPBHeader 
  2823.     short sessRefnum; /*Offset to session refnum*/
  2824.     char aspTimeout; /*Timeout for ATP*/
  2825.     char aspRetry; /*Retry count for ATP*/
  2826.     short cbSize; /*Command block size*/
  2827.     Ptr cbPtr; /*Command block pointer*/
  2828.     short rbSize; /*Reply buffer size*/
  2829.     Ptr rbPtr; /*Reply buffer pointer*/
  2830.     short wdSize; /*Write Data size*/
  2831.     Ptr wdPtr; /*Write Data pointer*/
  2832.     char ccbStart[296]; /*CCB memory allocated for driver afpWrite max size(CCB)=296 all other calls=150*/
  2833. }XPPPrmBlk;
  2834.  
  2835. æC 
  2836.  
  2837. æKY AFPLoginPrm
  2838. æFc AppleTalk.h
  2839. æT struct
  2840. æD typedef struct {
  2841.     XPPPBHeader 
  2842.     short sessRefnum; /*Offset to session refnum */
  2843.     char aspTimeout; /*Timeout for ATP */
  2844.     char aspRetry; /*Retry count for ATP */
  2845.     short cbSize; /*Command block size */
  2846.     Ptr cbPtr; /*Command block pointer */
  2847.     short rbSize; /*Reply buffer size */
  2848.     Ptr rbPtr; /*Reply buffer pointer */
  2849.     AddrBlock afpAddrBlock; /*block in AFP login */
  2850.     Ptr afpSCBPtr; /*SCB pointer in AFP login */
  2851.     Ptr afpAttnRoutine; /*routine pointer in AFP login */
  2852.     char ccbFill[144]; /*CCB memory allocated for driver  Login needs only 150 bytes BUT CCB really starts in the middle of AFPSCBPtr and also clobbers AFPAttnRoutine. */
  2853. }AFPLoginPrm;
  2854.  
  2855. æC 
  2856.  
  2857. æKY ASPOpenPrm
  2858. ASPOpenPrmPtr
  2859. æFc AppleTalk.h
  2860. æT struct
  2861. æD typedef struct {
  2862.     XPPPBHeader 
  2863.     short sessRefnum; /*Offset to session refnum */
  2864.     char aspTimeout; /*Timeout for ATP */
  2865.     char aspRetry; /*Retry count for ATP */
  2866.     AddrBlock serverAddr; /*Server address block */
  2867.     Ptr scbPointer; /*SCB pointer */
  2868.     Ptr attnRoutine; /*Attention routine pointer*/
  2869. }ASPOpenPrm;
  2870.  
  2871. typedef ASPOpenPrm *ASPOpenPrmPtr;
  2872.  
  2873. æC 
  2874.  
  2875. æKY ASPAbortPrm
  2876. æFc AppleTalk.h
  2877. æT struct
  2878. æD typedef struct {
  2879.     XPPPBHeader 
  2880.     Ptr abortSCBPtr; /*SCB pointer for AbortOS */
  2881. }ASPAbortPrm;
  2882.  
  2883. æC 
  2884.  
  2885. æKY ASPGetparmsBlk
  2886. æFc AppleTalk.h
  2887. æT struct
  2888. æD typedef struct {
  2889.     XPPPBHeader 
  2890.     short aspMaxCmdSize; /*For SPGetParms*/
  2891.     short aspQuantumSize;
  2892.     short numSesss;
  2893. }ASPGetparmsBlk;
  2894.  
  2895. æC 
  2896.  
  2897. æKY WDSElement
  2898. æFc AppleTalk.h
  2899. æT struct
  2900. æD typedef struct {
  2901.     short entryLength;
  2902.     Ptr entryPtr;
  2903. }WDSElement;
  2904.  
  2905. æC 
  2906.  
  2907. æKY NTElement
  2908. æFc AppleTalk.h
  2909. æT struct
  2910. æD typedef struct {
  2911.     AddrBlock nteAddress; /*network address of entity*/
  2912.     char filler;
  2913.     char entityData[99]; /*Object, Type & Zone*/
  2914. }NTElement;
  2915.  
  2916. æC 
  2917.  
  2918. æKY NamesTableEntry
  2919. æFc AppleTalk.h
  2920. æT struct
  2921. æD typedef struct {
  2922.     Ptr qNext; /*ptr to next NTE*/
  2923.     NTElement nt;
  2924. }NamesTableEntry;
  2925.  
  2926. æC 
  2927.  
  2928. æKY MPPATPHeader
  2929. æFc AppleTalk.h
  2930. æT struct
  2931. æD #define MPPATPHeader \
  2932.     QElem *qLink; /*next queue entry*/
  2933.     short qType; /*queue type*/
  2934.     short ioTrap; /*routine trap*/
  2935.     Ptr ioCmdAddr; /*routine address*/
  2936.     ProcPtr ioCompletion; /*completion routine*/
  2937.     OSErr ioResult; /*result code*/
  2938.     long userData; /*Command result (ATP user bytes)*/
  2939.     short reqTID; /*request transaction ID*/
  2940.     short ioRefNum; /*driver reference number*/
  2941.     short csCode; /*Call command code*/
  2942.  
  2943.  
  2944. æC 
  2945.  
  2946. æKY MPPparms
  2947. æFc AppleTalk.h
  2948. æT struct
  2949. æD typedef struct {
  2950.     MPPATPHeader 
  2951. }MPPparms;
  2952.  
  2953. æC 
  2954.  
  2955. æKY LAPparms
  2956. æFc AppleTalk.h
  2957. æT struct
  2958. æD typedef struct {
  2959.     MPPATPHeader 
  2960.     char protType; /*ALAP protocol Type */
  2961.     char filler;
  2962.     union {
  2963.     Ptr wdsPointer; /*-> write data structure*/
  2964.     Ptr handler; /*-> protocol handler routine*/
  2965.     } LAPptrs;
  2966. }LAPparms;
  2967.  
  2968. æC 
  2969.  
  2970. æKY DDPparms
  2971. æFc AppleTalk.h
  2972. æT struct
  2973. æD typedef struct {
  2974.     MPPATPHeader 
  2975.     char socket; /*socket number */
  2976.     char checksumFlag; /*check sum flag */
  2977.     union {
  2978.     Ptr wdsPointer; /*-> write data structure*/
  2979.     Ptr listener; /*->write data structure or -> Listener*/
  2980.     } DDPptrs;
  2981. }DDPparms;
  2982.  
  2983. æC 
  2984.  
  2985. æKY NBPparms
  2986. æFc AppleTalk.h
  2987. æT struct
  2988. æD typedef struct {
  2989.     MPPATPHeader 
  2990.     char interval; /*retry interval */
  2991.     char count; /*retry count */
  2992.     union {
  2993.     Ptr ntQElPtr;
  2994.     Ptr entityPtr;
  2995.     } NBPPtrs;
  2996.     union {
  2997.     char verifyFlag;
  2998.     struct {
  2999.     Ptr retBuffPtr;
  3000.     short retBuffSize;
  3001.     short maxToGet;
  3002.     short numGotten;
  3003.     } Lookup;
  3004.     struct {
  3005.     AddrBlock confirmAddr;
  3006.     char newSocket;
  3007.     } Confirm;
  3008.     } parm;
  3009. }NBPparms;
  3010.  
  3011. æC 
  3012.  
  3013. æKY SetSelfparms
  3014. æFc AppleTalk.h
  3015. æT struct
  3016. æD typedef struct {
  3017.     MPPATPHeader 
  3018.     char newSelfFlag; /*self-send toggle flag */
  3019.     char oldSelfFlag; /*previous self-send state */
  3020. }SetSelfparms;
  3021.  
  3022. æC 
  3023.  
  3024. æKY NBPKillparms
  3025. æFc AppleTalk.h
  3026. æT struct
  3027. æD typedef struct {
  3028.     MPPATPHeader 
  3029.     Ptr nKillQEl; /*ptr to i/o queue element to cancel */
  3030. }NBPKillparms;
  3031.  
  3032. æC 
  3033.  
  3034. æKY MPPParamBlock
  3035. MPPPBPtr
  3036. æFc AppleTalk.h
  3037. æT struct
  3038. æD typedef union {
  3039.     MPPparms MPP; /*General MPP parms*/
  3040.     LAPparms LAP; /*ALAP calls*/
  3041.     DDPparms DDP; /*DDP calls*/
  3042.     NBPparms NBP; /*NBP calls*/
  3043.     SetSelfparms SETSELF ;
  3044.     NBPKillparms NBPKILL ;
  3045. }MPPParamBlock;
  3046.  
  3047. typedef MPPParamBlock *MPPPBPtr;
  3048.  
  3049. æC 
  3050.  
  3051. æKY MOREATPHeader
  3052. æFc AppleTalk.h
  3053. æT struct
  3054. æD #define MOREATPHeader \
  3055.     char atpSocket; /*currbitmap for requests or ATP socket number*/
  3056.     char atpFlags; /*control information*/
  3057.     AddrBlock addrBlock; /*source/dest. socket address*/
  3058.     short reqLength; /*request/response length*/
  3059.     Ptr reqPointer; /*->request/response Data*/
  3060.     Ptr bdsPointer; /*->response BDS */
  3061.  
  3062.  
  3063. æC 
  3064.  
  3065. æKY ATPparms
  3066. æFc AppleTalk.h
  3067. æT struct
  3068. æD typedef struct {
  3069.     MPPATPHeader 
  3070.     MOREATPHeader 
  3071. }ATPparms;
  3072.  
  3073. æC 
  3074.  
  3075. æKY SendReqparms
  3076. æFc AppleTalk.h
  3077. æT struct
  3078. æD typedef struct {
  3079.     MPPATPHeader 
  3080.     MOREATPHeader 
  3081.     char filler; /*numOfBuffs */
  3082.     char timeOutVal; /*timeout interval */
  3083.     char numOfResps; /*number of responses actually received */
  3084.     char retryCount; /*number of retries */
  3085.     short intBuff; /*used internally for NSendRequest */
  3086. }SendReqparms;
  3087.  
  3088. æC 
  3089.  
  3090. æKY ATPmisc1
  3091. æFc AppleTalk.h
  3092. æT struct
  3093. æD typedef struct {
  3094.     MPPATPHeader 
  3095.     MOREATPHeader 
  3096.     union {
  3097.     char bitMap; /*bitmap received */
  3098.     char numOfBuffs; /*number of responses being sent*/
  3099.     char rspNum; /*sequence number*/
  3100.     } u0;
  3101. }ATPmisc1;
  3102.  
  3103. æC 
  3104.  
  3105. æKY ATPmisc2
  3106. æFc AppleTalk.h
  3107. æT struct
  3108. æD typedef struct {
  3109.     MPPATPHeader 
  3110.     MOREATPHeader 
  3111.     char filler;
  3112.     char bdsSize; /*number of BDS elements */
  3113.     short transID; /*transaction ID recd. */
  3114. }ATPmisc2;
  3115.  
  3116. æC 
  3117.  
  3118. æKY Killparms
  3119. æFc AppleTalk.h
  3120. æT struct
  3121. æD typedef struct {
  3122.     MPPATPHeader 
  3123.     MOREATPHeader 
  3124.     Ptr aKillQEl; /*ptr to i/o queue element to cancel*/
  3125. }Killparms;
  3126.  
  3127. æC 
  3128.  
  3129. æKY ATPParamBlock
  3130. ATPPBPtr
  3131. æFc AppleTalk.h
  3132. æT struct
  3133. æD typedef union {
  3134.     ATPparms ATP; /*General ATP parms*/
  3135.     SendReqparms SREQ; /*sendrequest parms*/
  3136.     ATPmisc1 OTH1; /*and a few others*/
  3137.     ATPmisc2 OTH2; /*and a few others*/
  3138.     Killparms KILL; /*and a few others */
  3139. }ATPParamBlock;
  3140.  
  3141. typedef ATPParamBlock *ATPPBPtr;
  3142.  
  3143. æC 
  3144.  
  3145. æKY XPPParamBlock
  3146. XPPParmBlkPtr
  3147. æFc AppleTalk.h
  3148. æT struct
  3149. æD typedef union {
  3150.     XPPPrmBlk XPP;
  3151.     ASPGetparmsBlk GETPARM;
  3152.     ASPAbortPrm ABORT;
  3153.     ASPOpenPrm OPEN;
  3154.     AFPLoginPrm LOGIN;
  3155. }XPPParamBlock;
  3156.  
  3157. typedef XPPParamBlock *XPPParmBlkPtr;
  3158.  
  3159. æC 
  3160.  
  3161. æKY OpenXPP
  3162. æFc AppleTalk.h
  3163. æT Function
  3164. æD pascal OSErr OpenXPP(short *xppRefnum); 
  3165. æDT OSErr myVariable = OpenXPP((short *) xppRefnum);
  3166. æRI  
  3167. æC 
  3168. »Opening the .XPP Driver
  3169.  
  3170. To open the .XPP driver, issue a Device Manager Open call.  (Refer to the Device
  3171. Manager chapter.)  The name of the .XPP driver is '.XPP'.  The original Macintosh
  3172. ROMs require that .XPP be opened only once. With new ROMs, the .XPP unit number can
  3173. always be obtained through an Open call.  With old ROMs only, the .XPP unit number
  3174. must be hard coded to XPPUnitNum (40) since only one Open call can be issued to the
  3175. driver.
  3176.  
  3177. The .XPP driver cannot be opened unless AppleTalk is open.  The application must
  3178. ensure that the .MPP and .ATP drivers are opened, as described earlier in this chapter.
  3179.  
  3180. The xppLoaded bit (bit 5) in the PortBUse byte in low memory indicates whether or not
  3181. the .XPP driver is open.
  3182.  
  3183. »Example
  3184.  
  3185. The following is an example of the procedure an application might use to open the
  3186. .XPP driver.
  3187.  
  3188. ;    Routine: OpenXPP
  3189. ;
  3190. ;        Open the .XPP driver and return the driver refNum for it.
  3191. ;
  3192. ;        Exit:    D0 = error code (ccr's set)
  3193. ;                 D1 = XPP driver refNum (if no errors)
  3194. ;
  3195. ;        All other registers preserved
  3196. ;
  3197. xppUnitNum    EQU    40                 ;default XPP driver number
  3198. xppTfRNum     EQU    -(xppUnitNum+1)    ;default XPP driver refNum
  3199.  
  3200. OpenXPP
  3201.     MOVE.L    A0-A1/D2,-(SP)            ;save registers
  3202.     MOVE      ROM85,D0                  ;check ROM type byte
  3203.     BPL.S     @10                       ;branch if >=128K ROMs
  3204.     BTST      #xppLoadedBit,PortBUse    ;is the XPP driver open already?
  3205.     BEQ.S     @10                       ;if not open, then branch to Open code
  3206.     MOVE      #xppTfRNum,D1             ;else use this as driver refnum
  3207.     MOVEQ     #0,D0                     ;set noErr
  3208.     BRA.S     @90                       ;and exit
  3209. ;
  3210. ; XPP driver not open. Make an _Open call to it. If using a 128K
  3211. ; ROM machine and the driver is already open, we will make another
  3212. ; Open call to it just so we get the correct driver refNum.
  3213. ;
  3214. @10 SUB       #ioQElSize,SP             ;allocate temporary param block
  3215.     MOVE.L    SP,A0                     ;A0 -> param block
  3216.     LEA       XPPName, A1               ;A1 -> XPP (ASP/AFP) driver name
  3217.     MOVE.L    A1,ioFileName(A0)         ;driver name into param block
  3218.     CLR.B     ioPermssn(A0)             ;clear permissions byte
  3219.     _Open
  3220.     MOVE      ioRefNum(A0),D1           ;D1=driver refNum (invalid if error)
  3221.     ADD       #ioQElSize,SP             ;deallocate temp param block
  3222. @90 MOVE.L    (SP)+,A0-A1/D2            ;restore registers
  3223.     TST       D0                        ;error? (set ccr's)
  3224.     RTS
  3225.     
  3226. XPPName  DC.B  4                        ;length of string
  3227.          DC.B  '.XPP'                   ;driver name
  3228.  
  3229. From Pascal, XPP can be opened through the OpenXPP call, which returns the driver’s
  3230. reference number:
  3231.  
  3232. FUNCTION OpenXPP (VAR xppRefnum: INTEGER) : OSErr;
  3233.  
  3234. »Open Errors
  3235.  
  3236. Errors returned when calling the Device Manager Open routine if the function does not
  3237. execute properly include the following:
  3238.  
  3239.   •  errors returned by System
  3240.   •  portInUse is returned if the AppleTalk port is in use by a driver
  3241.      other than AppleTalk or if AppleTalk is not open.
  3242.  
  3243. »Closing the .XPP Driver
  3244.  
  3245. To close the .XPP driver, call the Device Manager Close routine.
  3246.  
  3247. Warning:  There is generally no reason to close the driver.  Use this
  3248.           call sparingly, if at all.  This call should generally be used
  3249.           only by system-level applications.
  3250.  
  3251. »Close Errors
  3252.  
  3253. Errors returned when calling the Device Manager Close routine if the function does
  3254. not execute properly include the following:
  3255.  
  3256.   •  errors returned by System
  3257.   •  closeErr (new ROMs only) is returned if you try to close the driver
  3258.      and there are sessions active through that driver.  When sessions are
  3259.      active, closeErr is returned and the driver remains open.
  3260.   •  on old ROMs the driver is closed whether or not sessions are active
  3261.      and no error is returned. Results are unpredictable if sessions are
  3262.      still active.
  3263.  
  3264. »Session Control Block
  3265.  
  3266. The session control block (SCB) is a nonrelocatable block of data passed by the
  3267. caller to XPP upon session opening. XPP reserves this block for use in maintaining an
  3268. open session.   The SCB size is defined by the constant scbMemSize.  The SCB is a
  3269. locked block, and as long as the session is open, the SCB cannot be modified in any
  3270. way by the application.  There is one SCB for each open session. This block can be
  3271. reused once a CloseSess call is issued and completed for that session or when the
  3272. session is indicated as closed.
  3273.     
  3274.  
  3275. æKY ASPOpenSession
  3276. æFc AppleTalk.h
  3277. æT Function
  3278. æD pascal OSErr ASPOpenSession(ASPOpenPrmPtr thePBptr,Boolean async); 
  3279. æDT OSErr myVariable = ASPOpenSession((ASPOpenPrmPtr) thePBptr,(Boolean) async);
  3280. æRI V-536
  3281. æC 
  3282. »AppleTalk Session Protocol Functions
  3283.  
  3284. This section contains descriptions of the .XPP driver functions that you can call. 
  3285. Each function description shows the required parameter block fields, their offsets
  3286. within the parameter block and a brief definition of the field.  Possible result
  3287. codes are also described.
  3288.  
  3289. »Note on Result Codes
  3290.  
  3291. An important distinction exists between the aspParamErr and aspSessClose  result
  3292. codes that may be returned by the .XPP driver.
  3293.  
  3294. When the driver returns aspParamErr to a call that takes as an input a session reference
  3295. number, the session reference number does not relate to a valid open session.  There
  3296. could be several reasons for this, such as the workstation or server end closed the
  3297. session or the server end of the session died.
  3298.  
  3299. The aspSessClosed result code indicates that even though the session reference number
  3300. relates to a valid session, that particular session is in the process of closing down
  3301. (although  the session is not yet closed).
  3302.  
  3303. FUNCTION ASPOpenSession (xParamBlock: XPPParmBlkPtr; async: BOOLEAN) : OSErr;
  3304.  
  3305. Parameter block
  3306.   -->    26    csCode       word       Always ASPOpenSess
  3307.   -->    28    sessRefnum   word       Session reference number
  3308.   -->    30    aspTimeout   byte       Retry interval in seconds
  3309.   -->    31    aspRetry     byte       Number of retries
  3310.   -->    32    serverAddr   long word  Server socket address
  3311.   -->    36    scbPointer   pointer    Pointer to session control block
  3312.   -->    40    attnRoutine  pointer    Pointer to attention routine
  3313.  
  3314. ASPOpenSession initiates (opens) a session between the workstation and a server.  The
  3315. required parameter block is shown above.  A brief definition of the fields follows.
  3316.  
  3317. SessRefnum is a unique number identifying the open session between the workstation
  3318. and the server.  The SessRefnum is returned when the function completes successfully
  3319. and is used in all calls to identify the session.
  3320.  
  3321. ASPTimeOut is the interval in seconds between retries of the open session request.
  3322.  
  3323. ASPRetry is the number of retries that will be attempted.
  3324.  
  3325. ServerAddr is the network identifier or address of the socket on which the server is
  3326. listening.
  3327.  
  3328. SCBPointer points to a nonrelocatable block of data for the session control block
  3329. (SCB) that the .XPP driver reserves for use in maintaining an open session.   The SCB
  3330. size is defined by the constant scbMemSize.  The SCB is a locked block and as long as
  3331. the session is open, the SCB cannot be modified in any way by the application.  There
  3332. is one SCB for each open session.  This block can be reused when a CloseSess call is
  3333. issued and completed for that session, or when the session is indicated as closed
  3334. through return of aspParamErr as the result of a call for that session.
  3335.  
  3336. AttnRoutine is a pointer to a routine that is invoked if an attention from the server
  3337. is received, or upon session closing.  If this pointer is equal to zero, no attention
  3338. routine will be invoked.
  3339.  
  3340. Result codes    aspNoMoreSess    Driver cannot support another session
  3341.                 aspParamErr      Server returned bad (positive) error code    
  3342.                 aspNoServers     No servers at that address, or the server
  3343.                                  did not respond to the request
  3344.                 reqAborted       OpenSess was aborted by an AbortOS
  3345.                 aspBadVersNum    Server cannot support the offered 
  3346.                                  version number
  3347.                 aspServerBusy    Server cannot open another session
  3348.  
  3349. Note: The number of sessions that the driver is capable of supporting
  3350.       depends on the machine that the driver is running on. 
  3351.  
  3352. æKY ASPCloseSession
  3353. æFc AppleTalk.h
  3354. æT Function
  3355. æD pascal OSErr ASPCloseSession(XPPParmBlkPtr thePBptr,Boolean async); 
  3356. æDT OSErr myVariable = ASPCloseSession((XPPParmBlkPtr) thePBptr,(Boolean) async);
  3357. æRI V-537
  3358. æC  
  3359. Parameter block
  3360.   -->    26    csCode      word  Always ASPCloseSession
  3361.   -->    28    sessRefnum  word  Session reference number
  3362.  
  3363. ASPCloseSession closes the session identified by the sessRefnum returned in the
  3364. ASPOpenSession call.  ASPCloseSession aborts any calls that are active on the session,
  3365. closes the session, and calls the attention routine, if any, with an attention code
  3366. of zero (zero is invalid as a real attention code).
  3367.  
  3368. Result codes    aspParamErr      Parameter error, indicates an invalid
  3369.                                  session reference number
  3370.                 aspSessClosed    Session already in process of closing
  3371.  
  3372. æKY ASPAbortOS
  3373. æFc AppleTalk.h
  3374. æT Function
  3375. æD pascal OSErr ASPAbortOS(XPPParmBlkPtr thePBptr,Boolean async); 
  3376. æDT OSErr myVariable = ASPAbortOS((XPPParmBlkPtr) thePBptr,(Boolean) async);
  3377. æRI V-537
  3378. æC  
  3379. Parameter block
  3380.   -->    26    csCode            word     Always ASPAbortOS
  3381.   -->    28    abortSCBPointer   pointer  Pointer to session control block
  3382.  
  3383. ASPAbortOS aborts a pending (not yet completed) ASPOpenSession call.  The aborted
  3384. ASPOpenSession call will return a reqAborted error.
  3385.  
  3386. AbortSCBPointer points to the original SCB used in the the pending ASPOpenSession
  3387. call.
  3388.  
  3389. Result codes    cbNotFound    SCB not found, no outstanding open session
  3390.                               to be aborted.
  3391.                               Pointer did not point to an open session SCB.
  3392.  
  3393. æKY ASPGetParms
  3394. æFc AppleTalk.h
  3395. æT Function
  3396. æD pascal OSErr ASPGetParms(XPPParmBlkPtr thePBptr,Boolean async); 
  3397. æDT OSErr myVariable = ASPGetParms((XPPParmBlkPtr) thePBptr,(Boolean) async);
  3398. æRI V-538
  3399. æC  
  3400. Parameter block
  3401.   -->    26    csCode          word  Always ASPGetParms
  3402.   -->    28    aspMaxCmdSize   word  Maximum size of command block
  3403.   -->    30    aspQuantumSize  word  Maximum data size
  3404.   -->    32    numSesss        word  Number of sessions
  3405.  
  3406. ASPGetParms returns three ASP parameters.  This call does not require an open session.
  3407.  
  3408. ASPMaxCmdSize is the maximum size of a command that can be sent to the server.
  3409.  
  3410. ASPQuantumSize is the maximum size of data that can be transferred to the server in a
  3411. Write request or from the server in a command reply.
  3412.  
  3413. NumSess is the number of concurrent sessions supported by the driver.
  3414.  
  3415. æKY ASPCloseAll
  3416. æFc AppleTalk.h
  3417. æT Function
  3418. æD pascal OSErr ASPCloseAll(XPPParmBlkPtr thePBptr,Boolean async); 
  3419. æDT OSErr myVariable = ASPCloseAll((XPPParmBlkPtr) thePBptr,(Boolean) async);
  3420. æRI V-538
  3421. æC  
  3422. Parameter block
  3423.   -->    26    csCode  word  Always ASPCloseAll
  3424.  
  3425. ASPCloseAll closes every session that the driver has active, aborting all active
  3426. requests and invoking the attention routines where provided.  This call should be
  3427. used carefully.  ASPCloseAll can be used as a system level resource for making sure
  3428. all sessions are closed prior to closing the driver.
  3429.  
  3430. æKY ASPUserWrite
  3431. æFc AppleTalk.h
  3432. æT Function
  3433. æD pascal OSErr ASPUserWrite(XPPParmBlkPtr thePBptr,Boolean async); 
  3434. æDT OSErr myVariable = ASPUserWrite((XPPParmBlkPtr) thePBptr,(Boolean) async);
  3435. æRI V-538
  3436. æC  
  3437. Parameter block
  3438.   -->    18    cmdResult   long word  ASP command result
  3439.   -->    26    csCode      word       Always UserWrite
  3440.   -->    28    sessRefnum  word       Session reference number
  3441.   -->    30    aspTimeout  byte       Retry interval in seconds
  3442.   -->    32    cbSize      word       Command block size
  3443.   -->    34    cbPtr       pointer    Command block pointer
  3444.   <->    38    rbSize      word       Reply buffer size and reply size
  3445.   -->    40    rbPtr       pointer    Reply buffer pointer
  3446.   <->    44    wdSize      word       Write data size
  3447.   -->    46    wdPtr       pointer    Write data pointer
  3448.   -->    50    ccbStart    record     Start of memory for CCB
  3449.  
  3450. ASPUserWrite transfers data on a session.  ASPUserWrite is one of the two main calls
  3451. that can be used to transfer data on an ASP session.  The other call that performs a
  3452. similar data transfer  is ASPUserCommand described below.  The ASPUserWrite command
  3453. returns data in two different places.  Four bytes of data are returned in the cmdResult
  3454. field and a variable size reply buffer is also returned.
  3455.  
  3456. CmdResult is four bytes of data returned by the server.
  3457.  
  3458. SessRefnum is the session reference number returned in the ASPOpenSession call.
  3459.  
  3460. ASPTimeOut is the interval in seconds between retries of the call.  Notice that there
  3461. is no aspRetry field (retries are infinite).  The command will be retried at the
  3462. prescribed interval until completion or the session is closed.
  3463.  
  3464. CBSize is the size in bytes of the command data that is to be written on the session.
  3465.  The size of the command block must not exceed the value of aspMaxCmdSize returned by
  3466. the ASPGetParms call. Note that this buffer is not the data to be written by the
  3467. command but only the data of the command itself.
  3468.  
  3469. CBPtr points to the command data.
  3470.  
  3471. RBSize is passed and indicates the size of the reply buffer in bytes expected by the
  3472. command.  RBSize is also returned and indicates the size of the reply that was actually
  3473. returned.
  3474.  
  3475. RBPtr points to the reply buffer.
  3476.  
  3477. WDSize is passed and indicates the size of the write data in bytes to be sent by the
  3478. command.  WDSize is also returned and indicates the size of the write data that was
  3479. actually written.
  3480.  
  3481. WDPointer points to the write data buffer.
  3482.  
  3483. CCBStart is the start of the memory to be used by the .XPP driver for the command
  3484. control block.  The size of this block is equal to a maximum of 296 bytes.  To determine
  3485. the exact requirement, refer to the CCB Sizes section of this document.
  3486.  
  3487. Result codes     aspParamErr       Invalid session number, session has
  3488.                                    been closed
  3489.                  aspSizeErr        Command block size is bigger than MaxCmdSize
  3490.                  aspSessClosed     Session is closing
  3491.                  aspBufTooSmall    Reply is bigger than response buffer;
  3492.                                    the buffer will be filled, data will
  3493.                                    be truncated
  3494.  
  3495. æKY ASPUserCommand
  3496. æFc AppleTalk.h
  3497. æT Function
  3498. æD pascal OSErr ASPUserCommand(XPPParmBlkPtr thePBptr,Boolean async); 
  3499. æDT OSErr myVariable = ASPUserCommand((XPPParmBlkPtr) thePBptr,(Boolean) async);
  3500. æRI V-539
  3501. æC  
  3502. Parameter block
  3503.   -->    18    cmdResult   long word  ASP command result
  3504.   -->    26    csCode      word       Always ASPUserCommand
  3505.   -->    28    sessRefnum  word       Session number
  3506.   -->    30    aspTimeout  byte       Retry interval in seconds
  3507.   -->    32    cbSize      word       Command block size
  3508.   -->    34    cbPtr       pointer    Command block pointer
  3509.   <->    38    rbSize      word       Reply buffer and reply size
  3510.   -->    40    rbPtr       pointer    Reply buffer pointer
  3511.   -->    50    ccbStart    record     Start of memory for CCB
  3512.  
  3513. ASPUserCommand is used to send a command to the server on a session.
  3514.  
  3515. SessRefnum is the session reference number returned in the ASPOpenSession call.
  3516.  
  3517. ASPTimeOut is the interval in seconds between retries of the call.  Notice that there
  3518. is no aspRetry field (retries are infinite).  The command will be retried at the
  3519. prescribed interval until completion or the session is closed.
  3520.  
  3521. CBSize is the size in bytes of the block of data that contains the command to be sent
  3522. to the server on the session.  The size of the command block must not exceed the
  3523. value of aspMaxCmdSize returned by the ASPGetParms call.
  3524.  
  3525. CBPointer points to the block of data containing the command that is to be sent to
  3526. the server on the session.
  3527.  
  3528. RBSize is passed and indicates the size of the reply buffer in bytes expected by the
  3529. command.  RBSize is also returned and indicates the size of the reply that was actually
  3530. returned.
  3531.  
  3532. RBPtr points to the reply buffer.
  3533.  
  3534. CCBStart is the start of the memory to be used by the .XPP driver for the command
  3535. control block.  The size of this block is equal to a maximum of 150 bytes.  To determine
  3536. the exact requirement refer to the CCB Sizes section of this document.
  3537.  
  3538. Result codes     aspParamErr       Invalid session number, session has
  3539.                                    been closed
  3540.                  aspSizeErr        Command block size is bigger than MaxCmdSize
  3541.                  aspSessClosed     Session is closing
  3542.                  aspBufTooSmall    Reply is bigger than response buffer;
  3543.                                    the buffer will be filled, data will
  3544.                                    be truncated
  3545.  
  3546. æKY ASPGetStatus
  3547. æFc AppleTalk.h
  3548. æT Function
  3549. æD pascal OSErr ASPGetStatus(XPPParmBlkPtr thePBptr,Boolean async); 
  3550. æDT OSErr myVariable = ASPGetStatus((XPPParmBlkPtr) thePBptr,(Boolean) async);
  3551. æRI V-540
  3552. æC  
  3553. Parameter block
  3554.   -->    26    csCode      word       Always ASPGetStatus
  3555.   -->    30    aspTimeout  byte       Retry interval in seconds
  3556.   -->    31    aspRetry    byte       Number of retries
  3557.   -->    32    serverAddr  long word  Server socket address
  3558.   <->    38    rbSize      word       Reply buffer and reply size
  3559.   -->    40    rbPtr       pointer    Reply buffer pointer
  3560.   -->    50    ccbStart    record     Start of memory for CCB
  3561.  
  3562. ASPGetStatus returns server status.  This call is also used as GetServerInfo at the
  3563. AFP level. This call is unique in that it transfers data over the network without
  3564. having a session open.  This call does not pass any data but requests that server
  3565. status be returned.
  3566.  
  3567. ASPTimeOut is the interval in seconds between retries of the call.
  3568.  
  3569. ASPRetry is the number of retries that will be attempted.
  3570.  
  3571. ServerAddr is the network identifier or address of the socket on which the server is
  3572. listening.
  3573.  
  3574. RBSize is passed and indicates the size of the reply buffer in bytes expected by the
  3575. command. RBSize is also returned and indicates the size of the reply that was actually
  3576. returned.
  3577.  
  3578. RBPtr points to the reply buffer.
  3579.  
  3580. CCBStart is the start of the memory to be used by the .XPP driver for the command
  3581. control block.  The size of this block is equal to a maximum of 150 bytes.  To determine
  3582. the exact requirement refer to the CCB Sizes section of this document.
  3583.  
  3584. Result codes    aspBufTooSmall    Reply is bigger than response buffer,
  3585.                                   or Replysize is bigger than ReplyBuffsize
  3586.                 aspNoServer       No response from server at address used
  3587.                                   in call
  3588.  
  3589. æKY AFPCommand
  3590. æFc AppleTalk.h
  3591. æT Function
  3592. æD pascal OSErr AFPCommand(XPPParmBlkPtr thePBptr,Boolean async); 
  3593. æDT OSErr myVariable = AFPCommand((XPPParmBlkPtr) thePBptr,(Boolean) async);
  3594. æRI V-542
  3595. æC 
  3596. »AFPCall Function
  3597.  
  3598. The AFPCall function can have one of the following command formats.
  3599.  
  3600.   •  General
  3601.   •  Login
  3602.   •  AFPWrite
  3603.   •  AFPRead
  3604.  
  3605. »General Command Format
  3606.  
  3607. FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN) : OSErr;
  3608.  
  3609. Parameter block
  3610.   -->    18    cmdResult   long word  AFP command result
  3611.   -->    26    csCode      word       Always AFPCall
  3612.   -->    28    sessRefnum  word       Session reference number
  3613.   -->    30    aspTimeout  byte       Retry interval in seconds
  3614.   -->    32    cbSize      word       Command buffer size
  3615.   -->    34    cbPtr       pointer    Command buffer
  3616.   <->    38    rbSize      word       Reply buffer size and reply size
  3617.   -->    40    rbPtr       pointer    Reply buffer pointer
  3618.   <->    44    wdSize      word       Write data size
  3619.   -->    46    wdPtr       pointer    Write data pointer
  3620.   -->    50    ccbStart    record     Start of memory for CCB
  3621.  
  3622. The general command format for the AFPCall function passes an AFP command to the
  3623. server.  This format is used for all AFP calls except AFPLogin, AFPRead, and AFPWrite.
  3624.   Note that from Pascal this call is referred to as AFPCommand.
  3625.  
  3626. CmdResult is four bytes of data returned from the server containing an indication of
  3627. the result of the AFP command.
  3628.  
  3629. SessRefnum is the session reference number returned in the AFPLogin call.
  3630.  
  3631. ASPTimeOut is the interval in seconds between retries of the call by the driver.
  3632.  
  3633. CBSize is the size in bytes of the block of data that contains the command to be sent
  3634. to the server on the session. The size of the command block must not exceed the value
  3635. of aspMaxCmdSize returned by the ASPGetParms call.
  3636.  
  3637. CBPtr points to start of the block of data (command block) containing the command
  3638. that is to be sent to the server on the session.  The first byte of the command block
  3639. must contain the AFP command byte.  Subsequent bytes in the command buffer contain
  3640. the  parameters associated with the command as defined in the AFP document.
  3641.  
  3642. RBSize is passed and indicates the size of the reply buffer in bytes expected by the
  3643. command. RBSize is also returned and indicates the size of the reply that was actually
  3644. returned.
  3645.  
  3646. RBPtr points to the reply buffer.
  3647.  
  3648. WDSize is the size of data to be written to the server (only used if the command is
  3649. one that is mapped to an ASPUserWrite).
  3650.  
  3651. WDPtr points to the write data buffer (only used if the command is one that is mapped
  3652. to an ASPUserWrite).
  3653.  
  3654. CCBStart is the start of the memory to be used by the .XPP driver for the command
  3655. control block.  The size of this block is equal to a maximum of 296 bytes.  To determine
  3656. the exact requirement refer to the CCB Sizes section of this document.
  3657.  
  3658. Result codes    aspParamErr       Invalid session number; session has
  3659.                                   been closed
  3660.                 aspSizeErr        Command block size is bigger than MaxCmdSize
  3661.                 aspSessClosed     Session is closing
  3662.                 aspBufTooSmall    Reply is bigger than response buffer or
  3663.                                   buffer will be filled, data will be truncated
  3664.                 afpParmError      AFP command block size is equal to zero.
  3665.                                   This error will also be returned if the
  3666.                                   command byte in the command block is equal
  3667.                                   to 0 or $FF (255) or GetSrvrStatus (15).
  3668.  
  3669. »Login Command Format
  3670.  
  3671. The AFP login command executes a series of AFP operations as defined in the AFP Draft
  3672. Proposal.  For further information, refer to the AFP document.
  3673.  
  3674. FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN): OSErr;
  3675.  
  3676. Parameter block
  3677.   -->    18    cmdResult       long word  AFP command result
  3678.   -->    26    csCode          word       Always AFPCall
  3679.   -->    28    sessRefnum      word       Session reference number
  3680.   -->    30    aspTimeout      byte       Retry interval in seconds
  3681.   -->    31    aspRetry        byte       Number of retries
  3682.   -->    32    cbSize          word       Command buffer size
  3683.   -->    34    cbPtr           pointer    Command buffer
  3684.   <->    38    rbSize          word       Reply buffer size and reply size
  3685.   -->    40    rbPtr           pointer    Reply buffer pointer
  3686.   -->    44    afpAddrBlock    long word  Server address block
  3687.   <->    48    afpSCBPtr       pointer    SCB pointer
  3688.   <->    52    afpAttnRoutine  pointer    Attention routine pointer
  3689.   -->    50    ccbStart        record     Start of command control block
  3690.  
  3691. CmdResult is four bytes of data returned from the server containing an indication of
  3692. the result of the AFP command.
  3693.  
  3694. SessRefnum is the session reference number (returned by the AFPLogin call).
  3695.  
  3696. ASPTimeOut is the interval in seconds between retries of the call.
  3697.  
  3698. ASPRetry is the number of retries that will be attempted.
  3699.  
  3700. CBSize is the size in bytes of the block data that contains the command to be sent to
  3701. the server on the session. The size of the command block must not exceed the value of
  3702. aspMaxCmdSize returned by the ASPGetParms call.
  3703.  
  3704. CBPtr points to the block of data (command block) containing the AFP login command
  3705. that is to be sent to the server on the session.  The first byte of the command block
  3706. must be the AFP login command byte.  Subsequent bytes in the command buffer contain
  3707. the parameters associated with the command.
  3708.  
  3709. RBSize is passed and indicates the size of the reply buffer in bytes expected by the
  3710. command.  RBSize is also returned and indicates the size of the reply that was actually
  3711. returned.
  3712.  
  3713. RBPtr points to the reply buffer.
  3714.  
  3715. AFPServerAddr is the network identifier or address of the socket on which the server
  3716. is listening.
  3717.  
  3718. AFPSCBPointer points to a locked block of data for the session control block
  3719. (SCB). The SCB size is defined by scbMemSize.  The SCB is a locked block, and as long
  3720. as the session is open, the SCB cannot be modified in any way by the application. 
  3721. There is one SCB for each open session.
  3722.  
  3723. AFPAttnRoutine is a pointer to a routine that is invoked if an attention from the
  3724. server is received.  When afpAttnRoutine is equal to zero, no attention routine will
  3725. be invoked.
  3726.  
  3727. CCBStart is the start of the memory to be used by the .XPP driver for the command
  3728. control block.  The size of this block is equal to a maximum of 150 bytes.  To determine
  3729. the exact requirement refer to the CCB Sizes section later in this chapter.
  3730.  
  3731. Note:  In the parameter block, the afpSCBPointer and the afpAttnRoutine
  3732.        fields overlap with the start of the CCB and are modified by the call.
  3733.  
  3734. Result codes    aspSizeErr        Command block size is bigger than MaxCmdSize
  3735.                 aspBufTooSmall    Reply is bigger than response buffer or
  3736.                                   buffer will be filled, data will be truncated
  3737.                 aspNoServer       Server not responding
  3738.                 aspServerBusy     Server cannot open another session
  3739.                 aspBadVersNum     Server cannot support the offered ASP
  3740.                                   version number
  3741.                 aspNoMoreSess     Driver cannot support another session.
  3742.  
  3743.  
  3744. »AFPWrite Command Format
  3745.  
  3746. The AFPWrite and AFPRead command formats allow the calling application to make AFP-level
  3747. calls that read or write a data block that is larger than a single ASP-level call is
  3748. capable of reading or writing.  The maximum number of bytes of data that can be read
  3749. or written at the ASP level is equal to quantumSize.
  3750.  
  3751. FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN) : OSErr;
  3752.  
  3753. Parameter block
  3754.   -->    18    cmdResult   long word  AFP command result
  3755.   -->    26    csCode      word       Always AFPCall
  3756.   -->    28    sessRefnum  word       Session number
  3757.   -->    30    aspTimeout  byte       Retry interval in seconds
  3758.   -->    32    cbSize      word       Command buffer size
  3759.   -->    34    cbPtr       pointer    Command buffer
  3760.   <->    38    rbSize      word       Reply buffer size and reply size
  3761.   -->    40    rbPtr       pointer    Reply buffer pointer
  3762.   -->    44    wdSize      word       (used internally)
  3763.   <->    46    wdPtr       pointer    Write data pointer  (updated)
  3764.   -->    50    ccbStart    record     Start of memory for CCB
  3765.  
  3766. CmdResult is four bytes of data returned from the server containing an indication of
  3767. the result of the AFP command.
  3768.  
  3769. SessRefnum is the session reference number returned in the AFPLogin call.
  3770.  
  3771. ASPTimeOut is the interval in seconds between retries of the call.
  3772.  
  3773. CBSize is the size in bytes of the block data that contains the command to be sent to
  3774. the server on the session.  The size of the command block must not exceed the value
  3775. of aspMaxCmdSize returned by the aspGetParms call.
  3776.  
  3777. CBPtr points to the block of data (see command block structure below) containing the
  3778. AFP write command that is to be sent to the server on the session.  The first byte of
  3779. the Command Block must contain the AFP write command byte.
  3780.  
  3781. RBSize is passed and indicates the size of the reply buffer in bytes expected by the
  3782. command.  RBSize is also returned and indicates the size of the reply that was actually
  3783. returned.
  3784.  
  3785. RBPtr points to the reply buffer.
  3786.  
  3787. WDSize is used internally.
  3788.  
  3789. Note:  This command does not pass the write data size in the queue element
  3790.        but in the command buffer.  XPP will look for the size in that buffer.
  3791.  
  3792. WDPtr is a pointer to the block of data to be written.  Note that this field will be
  3793. updated by XPP as it proceeds and will always point to that section of the data which
  3794. XPP is currently writing.
  3795.  
  3796. CCBStart is the start of the memory to be used by the XPP driver for the command
  3797. control block.  The size of this block is equal to a maximum of 296 bytes.  To determine
  3798. the exact requirement refer to the CCB Sizes section later in this chapter.
  3799.  
  3800. Command Block Structure:  The AFP write command passes several arguments to XPP in
  3801. the command buffer itself. The byte offsets are relative to the location pointed to
  3802. by cbPtr.
  3803.  
  3804.   -->    0    cmdByte       byte       AFP call command byte
  3805.   -->    1    startEndFlag  byte       Start/end Flag
  3806.   <->    4    rwOffset      long word  Offset within fork to write
  3807.   <->    8    reqCount      long word  Requested count
  3808.  
  3809. CmdByte is the AFP call command byte and must contain the AFP write command code.
  3810.  
  3811. StartEndFlag is a one-bit flag (the high bit of the byte) indicating whether the
  3812. rwOffset field is relative to the beginning or the end of the fork (all other bits
  3813. are zero).
  3814.  
  3815.   0 = relative to the beginning of the fork
  3816.   1 = relative to the end of the fork
  3817.  
  3818. RWOffset is the byte offset within the fork at which the write is to begin.
  3819.  
  3820. ReqCount indicates the size of the data to be written and is returned as the actual
  3821. size written.
  3822.  
  3823. The rwOffset and reqCount fields are modified by XPP as the write proceeds and will
  3824. always indicate the current value of these fields.
  3825.  
  3826. The Pascal structure of the AFP command buffer follows:
  3827.  
  3828. AFPCommandBlock = PACKED RECORD
  3829.                     cmdByte:       Byte;
  3830.                     startEndFlag:  Byte;
  3831.                     forkRefNum:    INTEGER;    {used by server}
  3832.                     rwOffset:      LONGINT;
  3833.                     reqCount:      LONGINT;
  3834.                     newLineFlag:   Byte;       {unused by write}
  3835.                     newLineChar:   CHAR;       {unused by write}
  3836.                   END;
  3837.  
  3838. Result codes    aspParamErr       Invalid session number
  3839.                 aspSizeErr        Command block size is bigger than MaxCmdSize
  3840.                 aspSessClosed     Session is closing
  3841.                 aspBufTooSmall    Reply is bigger than response buffer
  3842.  
  3843. »AFPRead Command Format
  3844.  
  3845. The AFPWrite and AFPRead command formats allow the calling application to make AFP-level
  3846. calls that read or write a data block that is larger than a single ASP-level call is
  3847. capable of reading or writing.  The maximum number of bytes of data that can be read
  3848. or written at the ASP level is equal to quantumSize.
  3849.  
  3850. FUNCTION AFPCommand (xParamBlock: XPPParmBlkPtr; async: BOOLEAN) : OSErr;
  3851.  
  3852. Parameter block
  3853.   -->    18    cmdResult   long word  ASP command result
  3854.   -->    26    csCode      word       Always AFPCall
  3855.   -->    28    sessRefnum  word       Session number
  3856.   -->    30    aspTimeout  byte       Retry interval in seconds
  3857.   -->    32    cbSize      word       Command buffer size
  3858.   -->    34    cbPtr       pointer    Command buffer
  3859.   -->    38    rbSize      word       Used internally
  3860.   <->    40    rbPtr       pointer    Reply buffer pointer (updated)
  3861.   -->    50    ccbStart    record     Start of memory for CCB
  3862.  
  3863. CmdResult is four bytes of data returned from the server containing an indication of
  3864. the result of the AFP command.
  3865.  
  3866. SessRefnum is the session reference number returned in the AFPLogin  call.
  3867.  
  3868. ASPTimeOut is the interval in seconds between retries of the call.
  3869.  
  3870. CBSize is the size in bytes of the block data that contains the command to be sent to
  3871. the server on the session.  The size of the command block must not exceed the value
  3872. of aspMaxCmdSize returned by the GetParms call.
  3873.  
  3874. CBPtr points to the block of data (command block) containing the AFP read command
  3875. that is to be sent to the server on the session.  The first byte of the command block
  3876. must contain the AFP read command byte.  The command block structure is shown below.
  3877.  
  3878. RBSize  is used internally.
  3879.  
  3880. Note:  This command does not pass the read size in the queue element but
  3881.        in the command buffer.  XPP will look for the size in that buffer.
  3882.  
  3883. RBPtr points to the reply buffer.  Note that this field will be updated by XPP as it
  3884. proceeds and will always point to that section of the buffer that XPP is currently
  3885. reading into.
  3886.  
  3887. CCBStart is the start of the memory to be used by the .XPP driver for the command
  3888. control block.  The size of this block is equal to a maximum of 150 bytes.  To determine
  3889. the exact requirement refer to The CCB Sizes section later in this chapter.
  3890.  
  3891. Command Block Structure:  The AFP read command passes several arguments to XPP in the
  3892. command buffer itself. The byte offsets are relative to the location pointed to by
  3893. cbPointer.
  3894.  
  3895.   -->    0    cmdByte      byte       AFP call command byte
  3896.   <->    4    rwOffset     long word  Offset within fork to read
  3897.   <->    8    reqCount     long word  Requested count
  3898.   -->    12   newLineFlag  byte       Newline Flag
  3899.   -->    13   newLineChar  byte       Newline Character
  3900.  
  3901. CmdByte is the AFP call command byte and must contain the AFP read command code.
  3902.  
  3903. RWOffset is the byte offset within the fork at which the read is to begin.
  3904.  
  3905. ReqCount  indicates the size of the read data buffer and is returned as the actual
  3906. size read.
  3907.  
  3908. The rwOffset and reqCount fields are modified by XPP as the read proceeds and will
  3909. always indicate the current value of these fields.
  3910.  
  3911. NewLineFlag is a one-bit flag (the high bit of the byte) indicating whether or not
  3912. the read is to terminate at a specified character (all other bits are zero).
  3913.  
  3914.   0 = no Newline Character is specified
  3915.   1 = a Newline Character is specified
  3916.  
  3917. NewLineChar is any character from $00 to $FF (inclusive) that, when encountered in
  3918. reading the fork, causes the read operation to terminate.
  3919.  
  3920. The Pascal structure of the AFPCommand follows:
  3921.  
  3922. AFPCommandBlock = PACKED RECORD
  3923.                     cmdByte:       Byte;
  3924.                     startEndFlag:  Byte;     {unused for read}
  3925.                     forkRefNum:    INTEGER;  {used by server}
  3926.                     rwOffset:      LONGINT;
  3927.                     reqCount:      LONGINT;
  3928.                     newLineFlag:   Byte;
  3929.                     newLineChar:   CHAR;
  3930.                   END;
  3931.  
  3932. Result codes    aspParamErr       Invalid session number
  3933.                 aspSizeErr        Command block size is bigger than MaxCmdSize
  3934.                 aspSessClosed     Session is closing
  3935.                 aspBufTooSmall    Reply is bigger than response buffer
  3936.         
  3937.  
  3938. æKY GetLocalZones
  3939. æFc AppleTalk.h
  3940. æT Function
  3941. æD 
  3942. pascal OSErr GetLocalZones(XPPParmBlkPtr thePBptr,Boolean async); 
  3943. æDT OSErr myVariable = GetLocalZones((XPPParmBlkPtr) thePBptr,(Boolean) async);
  3944. æRI VI
  3945. æC 
  3946. Parameter block
  3947.   ¨  16  ioResult  word  result code 
  3948.   Æ  26  csCode  word  routine selector; always xCall
  3949.   Æ  28  xppSubCode  word  routine selector; getLocalZones
  3950.   Æ  30  xppTimeOut  byte  retry interval in seconds
  3951.   Æ  31  xppRetry  byte  retry count
  3952.   Æ  34  zipBuffPtr  pointer  pointer to data buffer
  3953.   ¨  38  zipNumZones  word  number of names returned
  3954.   ¨  40  zipLastFlag  byte  nonzero if no more names
  3955.   Æ  42  zipInfoField  70 bytes  for use by ZIP; first word set to 0
  3956.  
  3957. The GetLocalZones function returns a list of all the zone names on the local
  3958. network; that is, the network that includes the node on which your application
  3959. is running.
  3960.  
  3961. The ioResult parameter returns the result of the function; if you call the
  3962. function asynchronously, the function sets this field to 1 as soon as it begins
  3963. execution, and changes the field to the actual result code when it completes
  3964. execution. The csCode and xppSubCode parameters are routine selectors and are
  3965. automatically set by the MPW interface to xCall and getLocalZones for this
  3966. function. The xppTimeOut field specifies the amount of time, in seconds, that
  3967. the .ATP driver should wait between attempts to obtain the data. A value of 3 or
  3968. 4 for the xppTimeOut field generally gives good results. The xppRetry field
  3969. specifies the number of times the .ATP driver should attempt to obtain the data
  3970. before returning the ReqFailed (request failed) result code. A value of 3 or 4
  3971. for the xppRetry field usually works well.
  3972.  
  3973. The zipBuffPtr is a pointer to a 578-byte data buffer that you must allocate.
  3974. The Zone Information Protocol returns the zone names into this buffer as a
  3975. packed array of packed Pascal strings. The zipNumZones parameter returns the
  3976. number of zone names that ZIP placed in the data buffer. 
  3977.  
  3978. The .XPP driver sets the zipLastFlag field to 1 if there are no more zone names
  3979. for your network. If the zipLastFlag field is still 0 when the GetLocalZones
  3980. function has completed execution, you must empty the data buffer pointed to by
  3981. the zipBuffPtr parameter and immediately call the GetLocalZones function again
  3982. without changing the value in the zipInfoField parameter. The zipInfofield
  3983. parameter is a 70-byte data buffer that you must allocate for use by ZIP. You
  3984. must set the first word of this buffer to 0 before you call the GetLocalZones
  3985. function the first time, and not change the contents of this field thereafter.
  3986.         
  3987.  
  3988. æKY GetZoneList
  3989. æFc AppleTalk.h
  3990. æT Function
  3991. æD 
  3992. pascal OSErr GetZoneList(XPPParmBlkPtr thePBptr,Boolean async); 
  3993. æDT OSErr myVariable = GetZoneList((XPPParmBlkPtr) thePBptr,(Boolean) async);
  3994. æRI VI
  3995. æC 
  3996. Parameter block
  3997.   ¨  16  ioResult  word  result code 
  3998.   Æ  26  csCode  word  routine selector; always xCall
  3999.   Æ  28  xppSubCode  word  routine selector; getZoneList
  4000.   Æ  30  xppTimeOut  byte  retry interval in seconds
  4001.   Æ  31  xppRetry  byte  retry count
  4002.   Æ  34  zipBuffPtr  pointer  pointer to data buffer
  4003.   ¨  38  zipNumZones  word  number of names returned
  4004.   ¨  40  zipLastFlag  byte  nonzero if no more names
  4005.   Æ  42  zipInfoField  70 bytes  for use by ZIP; first word set to 0
  4006.  
  4007. The GetZoneList function returns a complete list of all the zone names on the
  4008. internet. Use the GetLocalZones function to obtain a list of only the zone names
  4009. on the local network. 
  4010.  
  4011. The ioResult parameter returns the result of the function; if you call the
  4012. function asynchronously, the function sets this field to 1 as soon as it begins
  4013. execution, and changes the field to the actual result code when it completes
  4014. execution. The csCode and xppSubCode parameters are routine selectors and are
  4015. automatically set by the MPW interface to xCall and getZoneList for this
  4016. function. The xppTimeOut field specifies the amount of time, in seconds, that
  4017. the .ATP driver should wait between attempts to obtain the data. A value of 3 or
  4018. 4 for the xppTimeOut field generally gives good results. The xppRetry field
  4019. specifies the number of times the .ATP driver should attempt to obtain the data
  4020. before returning the ReqFailed (request failed) result code. A value of 3 or 4
  4021. for the xppRetry field usually works well.
  4022.  
  4023. The zipBuffPtr is a pointer to a 578-byte data buffer that you must allocate.
  4024. The Zone Information Protocol returns the zone names into this buffer as Pascal
  4025. strings. The zipNumZones parameter returns the number of zone names that ZIP
  4026. placed in the data buffer. 
  4027.  
  4028. The .XPP driver sets the zipLastFlag field to 1 if there are no more zone names
  4029. for the internet. If the zipLastFlag field is still 0 when the GetZoneList
  4030. function has completed execution, you must empty the data buffer pointed to by
  4031. the zipBuffPtr parameter and immediately call the GetZoneList function again
  4032. without changing the value in the zipInfoField parameter. The zipInfofield
  4033. parameter is a 70-byte data buffer that you must allocate for use by ZIP. You
  4034. must set the first word of this buffer to 0 before you call the GetZoneList
  4035. function the first time, and not change the contents of this field thereafter.
  4036.         
  4037.  
  4038. æKY GetMyZone
  4039. æFc AppleTalk.h
  4040. æT Function
  4041. æD 
  4042. pascal OSErr GetMyZone(XPPParmBlkPtr thePBptr,Boolean async); 
  4043. æDT OSErr myVariable = GetMyZone((XPPParmBlkPtr) thePBptr,(Boolean) async);
  4044. æRI VI
  4045. æC 
  4046. The .XPP driver provides three functions that obtain information about zones.
  4047. All three functions use the Zone Information Protocol to return the names of
  4048. zones: The GetMyZone function returns the AppleTalk zone name of the node on
  4049. which your application is running; the GetLocalZones function returns a list of
  4050. zone names on the network that includes the node on which your application is
  4051. running; and the GetZoneList function returns a complete list of zones on the
  4052. internet.
  4053.  
  4054. Assembly-language note:  The .XPP driver functions all use the same value
  4055. (xCall, which is equal to 246) for the csCode parameter to the xCallParam
  4056. parameter block. The xCall routine uses the value of the xppSubCode parameter to
  4057. distinguish between the functions, as follows:
  4058.  
  4059. Function        xppSubCode      Value
  4060. GetMyZone       getMyZone       7
  4061. GetLocalZones   getLocalZones   5
  4062. GetZoneList     getZoneList     6
  4063.  
  4064. FUNCTION GetMyZone (thePBptr:XCallParamPtr; async: BOOLEAN) : OSErr;
  4065.  
  4066. Parameter block
  4067.   ¨  16  ioResult  word  result code 
  4068.   Æ  26  csCode  word  routine selector; always xCall
  4069.   Æ  28  xppSubCode  word  routine selector; getMyZone
  4070.   Æ  30  xppTimeOut  byte  retry interval in seconds
  4071.   Æ  31  xppRetry  byte  retry count
  4072.   Æ  34  zipBuffPtr  long  pointer to data buffer
  4073.   Æ  42  zipInfoField  70 bytes  for use by ZIP; first word set to 0
  4074.  
  4075. The GetMyZone function returns only the zone name of the node on which your
  4076. application is running.
  4077.  
  4078. The ioResult parameter returns the result of the function; if you call the
  4079. function asynchronously, the function sets this field to 1 as soon as it begins
  4080. execution, and changes the field to the actual result code when it completes
  4081. execution. The csCode and xppSubCode parameters are routine selectors and are
  4082. automatically set by the MPW interface to xCall and getMyZone for this function.
  4083. The xppTimeOut field specifies the amount of time, in seconds, that the .ATP
  4084. driver should wait between attempts to obtain the data. A value of 3 or 4 for
  4085. the xppTimeOut field generally gives good results. The xppRetry field specifies
  4086. the number of times the .ATP driver should attempt to obtain the data before
  4087. returning the ReqFailed (request failed) result code. A value of 3 or 4 for the
  4088. xppRetry field usually works well.
  4089.  
  4090. The zipBuffPtr is a pointer to a 33-byte data buffer that you must allocate. The
  4091. Zone Information Protocol returns the zone name into this buffer as a Pascal
  4092. string. The zipInfo field is a 70-byte data buffer that you must allocate for
  4093. use by ZIP. You must set the first word of this buffer to 0 before you call the
  4094. GetMyZone function.
  4095.  
  4096. Result codes
  4097. noErr          0  no error
  4098. noBridgeErr  –93  no router is available
  4099. reqFailed  –1096  Request to contact router failed; retry count exceeded 
  4100.         
  4101.  
  4102. æKY PAttachPH
  4103. æFc AppleTalk.h
  4104. æT Function
  4105. æD pascal OSErr PAttachPH(MPPPBPtr thePBptr,Boolean async); 
  4106. æDT OSErr myVariable = PAttachPH((MPPPBPtr) thePBptr,(Boolean) async);
  4107. æRI II-308, V-513
  4108. æC AttachPH function
  4109.  
  4110. Parameter block
  4111.     ->  26  csCode        word     ;always attachPH
  4112.     ->  28  protType      byte     ;ALAP protocol type
  4113.     ->  30  handler       pointer  ;protocol handler
  4114.  
  4115. AttachPH adds the protocol handler pointed to by handler to the node's protocol 
  4116. table.  ProtType specifies what kind of frame the protocol handler can service.  
  4117.  
  4118. After AttachPH is called, the protocol handler is called for each incoming frame 
  4119. whose ALAP protocol type equals protType.
  4120.  
  4121. Result codes    
  4122.  
  4123.       noErr         No error
  4124.       lapProtErr    Error attaching protocol type
  4125.  
  4126. æKY PDetachPH
  4127. æFc AppleTalk.h
  4128. æT Function
  4129. æD pascal OSErr PDetachPH(MPPPBPtr thePBptr,Boolean async); 
  4130. æDT OSErr myVariable = PDetachPH((MPPPBPtr) thePBptr,(Boolean) async);
  4131. æRI II-308, V-513
  4132. æC DetachPH function
  4133.  
  4134. Parameter block
  4135.     ->  26  csCode        word      ;always detachPH
  4136.     ->  28  protType      byte      ;ALAP protocol type
  4137.  
  4138. DetachPH removes from the node's protocol table the specified ALAP protocol type 
  4139. and corresponding protocol handler.
  4140.  
  4141. Result codes    
  4142.  
  4143.       noErr           No error
  4144.       lapProtErr      Error detaching protocol type
  4145.  
  4146. æKY PWriteLAP
  4147. æFc AppleTalk.h
  4148. æT Function
  4149. æD pascal OSErr PWriteLAP(MPPPBPtr thePBptr,Boolean async); 
  4150. æDT OSErr myVariable = PWriteLAP((MPPPBPtr) thePBptr,(Boolean) async);
  4151. æRI II-307, V-513
  4152. æC WriteLAP function
  4153.  
  4154. Parameter block
  4155.  
  4156.     ->  26  csCode          word       ;always writeLAP
  4157.     ->  30  wdsPointer      pointer    ;write data structure
  4158.  
  4159. WriteLAP sends a frame to another node.  The frame data and destination of the 
  4160. frame are described by the write data structure pointed to by wdsPointer.  The 
  4161. first two data bytes of an ALAP frame sent to another computer using the 
  4162. AppleTalk Manager must indicate the length of the frame in bytes.  The ALAP 
  4163. protocol type byte must be in the range 1 to 127.
  4164.  
  4165. Result codes    
  4166.  
  4167.       noErr          No error
  4168.       excessCollsns  No CTS received after 32 RTS's
  4169.       ddpLengthErr   Packet length exceeds maximum
  4170.       lapProtErr     Invalid ALAP protocol type
  4171.  
  4172. æKY POpenSkt
  4173. æFc AppleTalk.h
  4174. æT Function
  4175. æD pascal OSErr POpenSkt(MPPPBPtr thePBptr,Boolean async); 
  4176. æDT OSErr myVariable = POpenSkt((MPPPBPtr) thePBptr,(Boolean) async);
  4177. æRI II-311, V-513
  4178. æC OpenSkt function
  4179.  
  4180. Parameter block
  4181.  
  4182.     ->  26  csCode        word         ;always openSkt
  4183.     <-> 28  socket        byte         ;socket number
  4184.     ->  30  listener      pointer      ;socket listener
  4185.  
  4186. OpenSkt adds a socket and its socket listener to the socket table.  If the socket 
  4187. parameter is nonzero, it must be in the range 64 to 127, and it specifies the 
  4188. socket's number; if socket is 0, OpenSkt opens a socket with a socket number in the 
  4189. range 128 to 254, and returns it in the socket parameter.  Listener contains a 
  4190. pointer to the socket listener.
  4191.  
  4192. OpenSkt will return ddpSktErr if you pass the number of an already opened socket, 
  4193. if you pass a socket number greater than 127, or if the socket table is full (the 
  4194. socket table can hold a maximum of 12 sockets).
  4195.  
  4196. Result codes    
  4197.  
  4198.       noErr            No error
  4199.       ddpSktErr        Socket error
  4200.  
  4201. æKY PCloseSkt
  4202. æFc AppleTalk.h
  4203. æT Function
  4204. æD pascal OSErr PCloseSkt(MPPPBPtr thePBptr,Boolean async); 
  4205. æDT OSErr myVariable = PCloseSkt((MPPPBPtr) thePBptr,(Boolean) async);
  4206. æRI II-312,V513
  4207. æC CloseSkt function
  4208.  
  4209. Parameter block
  4210.  
  4211.     ->  26  csCode  word    ;always closeSkt
  4212.     ->  28  socket  byte    ;socket number
  4213.  
  4214. CloseSkt removes the entry of the specified socket from the socket table.  If you 
  4215. pass a socket number of 0, or if you attempt to close a socket that isn't open, 
  4216. CloseSkt will return ddpSktErr.
  4217.  
  4218. Result codes    
  4219.  
  4220.       noErr         No error
  4221.       ddpSktErr     Socket error
  4222.  
  4223. æKY PWriteDDP
  4224. æFc AppleTalk.h
  4225. æT Function
  4226. æD pascal OSErr PWriteDDP(MPPPBPtr thePBptr,Boolean async); 
  4227. æDT OSErr myVariable = PWriteDDP((MPPPBPtr) thePBptr,(Boolean) async);
  4228. æRI II-312,V-513
  4229. æC WriteDDP function
  4230.  
  4231. Parameter block
  4232.  
  4233.     ->  26  csCode            word        ;always writeDDP
  4234.     ->  28  socket            byte        ;socket number
  4235.     ->  29  checksumFlag      byte        ;checksum flag
  4236.     ->  30  wdsPointer        pointer     ;write data structure
  4237.  
  4238. WriteDDP sends a datagram to another socket.  WDSPointer points to a write data 
  4239. structure containing the datagram and the address of the destination socket.  If 
  4240. checksumFlag is TRUE, WriteDDP will compute the checksum for all datagrams 
  4241. requiring long headers.
  4242.  
  4243. Result codes    
  4244.  
  4245.       noErr          No error
  4246.       ddpLenErr      Datagram length too big
  4247.       ddpSktErr      Socket error
  4248.       noBridgeErr    No bridge found 
  4249.  
  4250. æKY PRegisterName
  4251. æFc AppleTalk.h
  4252. æT Function
  4253. æD pascal OSErr PRegisterName(MPPPBPtr thePBptr,Boolean async); 
  4254. æDT OSErr myVariable = PRegisterName((MPPPBPtr) thePBptr,(Boolean) async);
  4255. æRI II-322,V-513
  4256. æC RegisterName function
  4257.  
  4258. Parameter block
  4259.  
  4260.     ->  26  csCode           word       ;always registerName
  4261.     ->  28  interval         byte       ;retry interval
  4262.     <-> 29  count            byte       ;retry count
  4263.     ->  30  ntQElPtr         pointer    ;names table element pointer 
  4264.     ->  34  verifyFlag       byte       ;set if verify needed 
  4265.  
  4266. RegisterName adds the name and address of an entity to the node's names table.  
  4267. NTQElPtr points to a names table entry containing the entity's name and internet 
  4268. address (in the form shown in Figure 13 above).  Meta-characters aren't allowed in 
  4269. the object and type fields of the entity name; the zone field, however, must contain 
  4270. the meta-character "*".  If verifyFlag is TRUE, RegisterName checks on the network 
  4271. to see if the name is already in use, and returns a result code of nbpDuplicate if so.  
  4272.  
  4273. Interval and count contain the retry interval in eight-tick units and the retry count.  
  4274. When a retry is made, the count field is modified.
  4275.  
  4276. Warning:  The names table entry passed to RegisterName remains the 
  4277.           property of NBP until removed from the names table.  Don't attempt to remove 
  4278.           or modify it.  If you've allocated memory using a NewHandle call, you must 
  4279.           lock it as long as the name is registered. 
  4280.  
  4281. Warning:  VerifyFlag should normally be set before calling RegisterName.
  4282.  
  4283. Result codes    
  4284.  
  4285.    noErr             No error
  4286.    nbpDuplicate      Duplicate name already exists
  4287.    nbpNISErr         Error opening names information socket 
  4288.  
  4289. æKY PLookupName
  4290. æFc AppleTalk.h
  4291. æT Function
  4292. æD pascal OSErr PLookupName(MPPPBPtr thePBptr,Boolean async); 
  4293. æDT OSErr myVariable = PLookupName((MPPPBPtr) thePBptr,(Boolean) async);
  4294. æRI II-323,V-513
  4295. æC LookupName function
  4296.  
  4297. Parameter block
  4298.  
  4299.     ->   26 csCode             word         ;always lookupName
  4300.     ->      28  interval       byte         ;retry interval
  4301.     <->     29  count          byte         ;retry count
  4302.     ->      30  entityPtr      pointer      ;pointer to entity name
  4303.     ->      34  retBuffPtr     pointer      ;pointer to buffer
  4304.     ->      38  retBuffSize    word         ;buffer size in bytes
  4305.     ->      40  maxToGet       word         ;matches to get
  4306.     <->     42  numGotten      word         ;matches found 
  4307.  
  4308. LookupName returns the addresses of all entities with a specified name.  EntityPtr 
  4309. points to the entity's name (in the form shown in Figure 13 above).  Meta-
  4310. characters are allowed in the entity name.  RetBuffPtr and retBuffSize contain the 
  4311. location and size of an area of memory in which the tuples describing the entity 
  4312. names and their corresponding addresses should be returned.  MaxToGet indicates 
  4313. the maximum number of matching names to find addresses for; the actual number of 
  4314. addresses found is returned in numGotten.  Interval and count contain the retry 
  4315. interval and the retry count.  LookupName completes when either the number of 
  4316. matches is equal to or greater than maxToGet, or the retry count has been exceeded.  
  4317. The count field is decremented for each retransmission.
  4318.  
  4319. Note:  NumGotten is first set to 0 and then incremented with each match 
  4320.        found.  You can test the value in this field, and can start examining the 
  4321.        received addresses in the buffer while the lookup continues.
  4322.  
  4323. Result codes    
  4324.  
  4325.       noErr           No error
  4326.       nbpBuffOvr      Buffer overflow
  4327.  
  4328. æKY PConfirmName
  4329. æFc AppleTalk.h
  4330. æT Function
  4331. æD pascal OSErr PConfirmName(MPPPBPtr thePBptr,Boolean async); 
  4332. æDT OSErr myVariable = PConfirmName((MPPPBPtr) thePBptr,(Boolean) async);
  4333. æRI II-323,V-513
  4334. æC ConfirmName function
  4335.  
  4336. Parameter block
  4337.  
  4338.     ->   26 csCode            word         ;always confirmName
  4339.     ->   28 interval          byte         ;retry interval
  4340.     <->  29  count            byte         ;retry count
  4341.     ->   30 entityPtr         pointer      ;pointer to entity name
  4342.     ->   34 confirmAddr       pointer      ;entity address
  4343.     <-   38 newSocket         byte         ;socket number
  4344.  
  4345. ConfirmName confirms that an entity known by name and address still exists (is 
  4346. still entered in the names directory).  EntityPtr points to the entity's name (in the 
  4347. form shown in Figure 13 above).  ConfirmAddr specifies the address to confirmed.  
  4348.  
  4349. No meta-characters are allowed in the entity name.  Interval and count contain the 
  4350. retry interval and the retry count.  The socket number of the entity is returned in 
  4351. newSocket.  ConfirmName is more efficient than LookupName in terms of network 
  4352. traffic.
  4353.  
  4354. Result codes    
  4355.  
  4356.       noErr             No error
  4357.       nbpConfDiff       Name confirmed for different socket
  4358.       nbpNoConfirm      Name not confirmed
  4359.  
  4360. æKY PRemoveName
  4361. æFc AppleTalk.h
  4362. æT Function
  4363. æD pascal OSErr PRemoveName(MPPPBPtr thePBptr,Boolean async); 
  4364. æDT OSErr myVariable = PRemoveName((MPPPBPtr) thePBptr,(Boolean) async);
  4365. æRI II-324,V-513
  4366. æC RemoveName function
  4367.  
  4368. Parameter block
  4369.  
  4370.     ->  26  csCode        word        ;always removeName 
  4371.     ->  30  entityPtr     pointer     ;pointer to entity name 
  4372.  
  4373. RemoveName removes an entity name from the names table of the given entity's node.
  4374.  
  4375. Result codes    
  4376.  
  4377.    noErr            No error
  4378.    nbpNotFound      Name not found 
  4379.  
  4380. æKY PSetSelfSend
  4381. æFc AppleTalk.h
  4382. æT Function
  4383. æD pascal OSErr PSetSelfSend(MPPPBPtr thePBptr,Boolean async); 
  4384. æDT OSErr myVariable = PSetSelfSend((MPPPBPtr) thePBptr,(Boolean) async);
  4385. æRI V-516
  4386. æC  
  4387. _______________________________________________________________________________
  4388.  
  4389. »SENDING PACKETS TO ONE’S OWN NODE
  4390. _______________________________________________________________________________
  4391.  
  4392. Upon opening, the ability to send a packet to one’s own node (intranode delivery) is
  4393. disabled.  This feature of the AppleTalk Manager can be manipulated through the
  4394. SetSelfSend function.  Once enabled, it is possible, at all levels, to send packets
  4395. to entities within one’s own node.  An example of where this might be desirable is an
  4396. application sending data to a print spooler that is actually running in the background
  4397. on the same node.
  4398.  
  4399. Enabling (or disabling) this feature affects the entire node and should be performed
  4400. with care.  For instance, a desk accessory may not expect to receive names from
  4401. within its own node as a response to an NBP look-up;  enabling this feature from an
  4402. application could break the desk accessory.  All future programs should be written
  4403. with this feature in mind.
  4404.  
  4405. FUNCTION PSetSelfSend (thePBptr: MPPPBPtr; async: BOOLEAN) : OSErr;
  4406.  
  4407. Parameter Block
  4408.   -->    26    csCode         word    Always PSetSelfSend
  4409.   -->    28    newSelfFlag    byte    New SelfSend flag
  4410.   <--    29    oldSelfFlag    byte    Old SelfSend flag
  4411.  
  4412. PSetSelfSend enables or disables the intranode delivery feature of the AppleTalk
  4413. Manager.  If newSelfFlag is nonzero, the feature will be enabled; otherwise it will
  4414. be disabled.  The previous value of the flag will be returned in oldSelfFlag.
  4415.  
  4416. Result Codes    noErr        No error
  4417.  
  4418. æKY PKillNBP
  4419. æFc AppleTalk.h
  4420. æT Function
  4421. æD pascal OSErr PKillNBP(MPPPBPtr thePBptr,Boolean async); 
  4422. æDT OSErr myVariable = PKillNBP((MPPPBPtr) thePBptr,(Boolean) async);
  4423. æRI V-518
  4424. æC  
  4425. _______________________________________________________________________________
  4426.  
  4427. »NAME BINDING PROTOCOL CHANGES
  4428. _______________________________________________________________________________
  4429.  
  4430. Changes to the Name Binding Protocol include supporting multiple concurrent requests
  4431. and a means for aborting an active request.
  4432.  
  4433. »Multiple Concurrent NBP Requests
  4434.  
  4435. NBP now supports multiple concurrent active requests.  Specifically, a number of
  4436. LookupNames, RegisterNames and ConfirmNames can all be active concurrently.  The
  4437. maximum number of  concurrent requests is machine dependent; if it is exceeded the
  4438. error tooManyReqs will be returned.  Active requests can be aborted by the PKillNBP
  4439. call.
  4440.  
  4441. »KillNBP function
  4442.  
  4443. FUNCTION PKillNBP (thePBptr: ATPPBPtr; async: BOOLEAN) : OSErr;
  4444.  
  4445. •••Refer to Technical Note #199:•••
  4446.  
  4447. Parameter block
  4448.   -->    26    csCode    word     Always PKillNBP
  4449.   -->    28    aKillQEl  pointer  Pointer to queue element
  4450.  
  4451. PKillNBP is used to abort an outstanding LookupName, RegisterName or ConfirmName
  4452. request.  To abort one of these calls, place a pointer to the queue element of the
  4453. call to abort in a KillQEl and issue the PKillNBP call.  The call will be completed
  4454. with a ReqAborted error.
  4455.  
  4456. Result Codes    noErr          No error
  4457.                 cbNotFound     aKillQEl does not point to a valid
  4458.                                NBP queue element
  4459.  
  4460. æKY PGetAppleTalkInfo
  4461. æFc AppleTalk.h
  4462. æT Function
  4463. æD 
  4464. pascal OSErr PGetAppleTalkInfo(MPPPBPtr thePBptr,Boolean async); 
  4465. æDT OSErr myVariable = PGetAppleTalkInfo((MPPPBPtr) thePBptr,(Boolean) async);
  4466. æRI VI
  4467. æC  
  4468. You can use the PGetAppleTalkInfo function to obtain information about the .MPP
  4469. driver. In addition to the node ID and other information pointed to by the
  4470. ABusVars global variable (discussed in the AppleTalk Manager chapter of Volume
  4471. II), the PGetAppleTalkInfo function returns 
  4472.  
  4473.   •   a pointer to the .MPP driver’s device control entry data structure (DCE)
  4474.  
  4475.   •   configuration flags, which indicate the status of certain conditions that
  4476.       are set at startup
  4477.  
  4478.   •   a value (the selfSend flag) that indicates whether the node can send
  4479.       packets to itself
  4480.  
  4481.   •   the network number range for the network to which the node is attached
  4482.  
  4483.   •   the 8-bit node ID and 16-bit network number of the node
  4484.  
  4485.   •   the 8-bit node ID and 16-bit network number of the last router from which
  4486.       the node has heard
  4487.  
  4488.   •   the maximum capacities of the .MPP driver—such as the maximum number of
  4489.       protocol handlers and the maximum number of static sockets allowed by
  4490.       this driver
  4491.  
  4492.   •   a pointer to the registered names queue
  4493.  
  4494.   •   the node address of the node on the underlying data link (for example,
  4495.       the Ethernet hardware address)
  4496.  
  4497.   •   the node’s zone name
  4498.  
  4499. The data link address (for example, the Ethernet hardware address) and the zone
  4500. name are returned only for extended networks; that is, network types that allow
  4501. more than one network per cable. You must allocate memory for and provide
  4502. pointers to the data buffers into which the PGetAppleTalkInfo function returns
  4503. the data link address and zone name. You use the laLength parameter to specify
  4504. the length of the data link address you want returned; the function returns the
  4505. actual length of the data in the laLength parameter and returns the data in the
  4506. buffer you provide.
  4507.  
  4508. Note:  Always use the PGetAppleTalkInfo function to obtain information about the
  4509. .MPP driver. You can no longer rely on the validity of the global variables
  4510. described in the AppleTalk chapter of Inside Macintosh, Volume II.
  4511.  
  4512. FUNCTION PGetAppleTalkInfo (thePBptr: MPPPBPtr; async: BOOLEAN) : OSErr;
  4513.  
  4514. Parameter block
  4515.   ¨  16  ioResult  word  result code 
  4516.   Æ  26  csCode  word  always PGetAppleTalkInfo
  4517.   Æ  28  version  word  version of function
  4518.   ¨  30  varsPtr  pointer  pointer to MPP globals
  4519.   ¨  34  dcePtr  pointer  pointer to DCE for .MPP
  4520.   ¨  38  portID  word  port number 
  4521.   ¨  40  configuration  long  configuration flags
  4522.   ¨  44  selfSend  word  nonzero if self-send is enabled
  4523.   ¨  46  netLo  word  low value of the network range
  4524.   ¨  48  netHi  word  high value of the network range
  4525.   ¨  50  ourAddr  long  local 24-bit AppleTalk address
  4526.   ¨  54  routerAddr  long  24-bit address of router
  4527.   ¨  58  numOfPHs  word  max number of protocol handlers
  4528.   ¨  60  numOfSkts  word  max number of static sockets
  4529.   ¨  62  numNBPEs  word  max concurrent NBP requests
  4530.   ¨  64  ntQueue  pointer  pointer to registered name queue
  4531.   ´  68  laLength  word  length in bytes of data link address
  4532.           (extended networks only)
  4533.   Æ  70  linkAddr  pointer  pointer to data link address buffer
  4534.           (extended networks only)
  4535.   Æ  74  zoneName  pointer  pointer to zone name buffer
  4536.  
  4537. The PGetAppleTalkInfo function returns information about the .MPP driver. If the
  4538. node on which your program is running happens also to be running AppleTalk
  4539. Internet Router software in the background, there may be more than one set of 
  4540. .MPP global variables in RAM. To make sure you are obtaining information about
  4541. the .MPP driver that handles application software, always use the
  4542. PGetAppleTalkInfo function rather than the Device Manager’s PBControl function.
  4543. If you are using assembly language, or want to use the PBControl function, you
  4544. must use a device driver reference number of –10 for the .MPP driver.
  4545.  
  4546. Parameters
  4547.  
  4548. ioResult
  4549. The result of the function. When you execute the function asynchronously, the
  4550. function sets this parameter to 1 and returns a function result of noErr as soon
  4551. as the function begins execution. When the function completes execution, it sets
  4552. the ioResult parameter to the actual result code. 
  4553.  
  4554. csCode
  4555. Routine selector, automatically set by the MPW interface. Always equal to
  4556. PGetAppleTalkInfo for this function.
  4557.  
  4558. version
  4559. The version number of the PGetAppleTalkInfo function you are calling. For
  4560. version number 53 of the .MPP driver, this number is always 1.
  4561.  
  4562. varsPtr
  4563. A pointer to the MPP global variables. The MPP global variables are discussed in
  4564. “Protocol Handlers and Socket Listeners” in Chapter 10 of Volume II.
  4565.  
  4566. dcePtr
  4567. A pointer to the device control entry (DCE) data structure for the .MPP driver.
  4568. The DCE is described in the Device Manager chapters of Volumes II and V.
  4569.  
  4570. portID
  4571. The port number for the .MPP driver. The port number is always 0 unless you are
  4572. requesting information for an .MPP driver being used by a router.
  4573.  
  4574. configuration
  4575. A 32-bit long word of configuration flags. The following flags are currently
  4576. defined:
  4577.  
  4578. Bit  Flag       Description
  4579. 31   SrvAdrBit  TRUE (1) if the routine that opened the .MPP driver requested a
  4580. server node number. Server node numbers are described in the AppleTalk Manager
  4581. of Volume V. This flag indicates only that the server-node number was requested,
  4582. not that it was returned. Some AppleTalk devices, such as EtherTalk, do not
  4583. honor a request for a server-node number.
  4584.  
  4585. 30   RouterBit  TRUE (1) if an AppleTalk Internet Router was loaded at system
  4586. startup (that is, there's a router operating on the same node as your
  4587. application). A router can be loaded but not active.
  4588.  
  4589. 15   ExtendedBit  TRUE (1) if the node is on an extended network.
  4590.  
  4591. 7    BadZoneHintBit  TRUE (1) if the zone name of the node you are on was not
  4592. the same as the zone name stored in parameter RAM (sometimes referred to as the
  4593. zone name hint) when the .MPP driver was opened. If the zone name hint is
  4594. invalid, then the AppleTalk Manager uses the default zone for the network.
  4595.  
  4596. 6    OneZoneBit  TRUE (1) if only one zone is assigned to your extended network
  4597. or if you are not on an extended network.
  4598.  
  4599. selfSend
  4600. This parameter is nonzero if the ability of a node to send packets to itself is
  4601. enabled. Use the PSetSelfSend function, described in the AppleTalk Manager
  4602. chapter of Volume V, to enable or disable this feature.
  4603.  
  4604. netLo
  4605. The low value of the range of network numbers on the local cable. Only extended
  4606. networks can have a range of network numbers. For a nonextended network, this
  4607. parameter returns the network number.
  4608.  
  4609. netHi
  4610. The high value of the range of network numbers on the local cable. Only extended
  4611. networks can have a range of network numbers. For a nonextended network, this
  4612. parameter returns the network number.
  4613.  
  4614. ourAddr
  4615. The 24-bit AppleTalk network address of the node you are on. The least
  4616. significant byte of the longword is the node ID. The middle 16 bits are the
  4617. network number. The most significant byte of the longword is reserved for use by
  4618. Apple Computer, Inc. 
  4619.  
  4620. routerAddr
  4621. The 24-bit AppleTalk network address of the last router from which your node
  4622. heard traffic. The least significant byte of the longword is the node ID. The
  4623. middle 16 bits are the network number. The most significant byte of the longword
  4624. is reserved for use by Apple Computer, Inc. You should always use this address
  4625. when you want to communicate with a router.
  4626.  
  4627. numOfPHs
  4628. The maximum number of protocol handlers that this .MPP driver allows.
  4629.  
  4630. numOfSkts
  4631. The maximum number of statically assigned sockets that this .MPP driver allows.
  4632. Statically assigned sockets are described in Inside AppleTalk.
  4633.  
  4634. numNBPEs
  4635. The maximum number of concurrent requests to NBP that this .MPP driver allows. 
  4636.  
  4637. ntQueue
  4638. A pointer to the first entry in the names table for the local node. You can use
  4639. NBP routines to look up and register names in the names table. The names table
  4640. is described in “Name-Binding Protocol” in Chapter 10 of Volume II.
  4641.  
  4642. laLength
  4643. When you call the PGetAppleTalkInfo function on a node on an extended network,
  4644. you use this parameter to specify the number of bytes of the data link address
  4645. the function should place in the buffer pointed to by the LinkAddr parameter. If
  4646. you request more bytes than the total number of bytes in the address, then the
  4647. function returns in the laLength parameter the actual number of bytes it placed
  4648. in the buffer. If the address is longer than the size of the buffer, then the
  4649. PGetAppleTalkInfo function fills the buffer and returns in the laLength
  4650. parameter the actual length of the address, not the number of bytes returned.
  4651. The function does not return an error when the buffer is too large or too small
  4652. for the address.
  4653.  
  4654. linkAddr
  4655. A pointer to a buffer for the data link address returned for extended networks
  4656. only. You use the laLength parameter to specify the number of bytes of the
  4657. address that you want placed in this buffer. You must allocate a buffer large
  4658. enough to hold the number of bytes you specify. Speficy NIL for this parameter
  4659. if you do not want the function to provide a data-link address.
  4660.  
  4661. zoneName
  4662. A pointer to a buffer into which the PGetAppleTalkInfo function places the local
  4663. node’s zone name. You must allocate a buffer of at least 33 bytes to hold this
  4664. data, or specify NIL for the ZoneName parameter if you do not want to obtain the
  4665. zone name. This field is returned only if the node is on an extended network.
  4666.  
  4667. Result codes
  4668. noErr  0  no error
  4669.  
  4670.  
  4671.  
  4672. æKY PATalkClosePrep
  4673. æFc AppleTalk.h
  4674. æT Function
  4675. æD 
  4676. pascal OSErr PATalkClosePrep(MPPPBPtr thePBptr,Boolean async); 
  4677. æDT OSErr myVariable = PATalkClosePrep((MPPPBPtr) thePBptr,(Boolean) async);
  4678. æRI VI
  4679. æC  
  4680. Whereas it is unlikely that opening the .MPP driver will adversely affect
  4681. another program, an application should never close the .MPP driver, because
  4682. another program might be using it. Under certain circumstances, however, the
  4683. system might close the .MPP driver, provided no application objects. The system
  4684. uses the .MPP driver’s PATalkClosePrep function to inform each routine in the
  4685. AppleTalk Transition Queue that it intends to close the .MPP driver, giving each
  4686. routine in the queue the opportunity to deny permission to do so.
  4687.  
  4688. The system provides a pointer to a 255-byte buffer when it calls the
  4689. PATalkClosePrep function. If any routine in the AppleTalk Transition Queue
  4690. denies permission to close the .MPP driver, it places a name in the buffer and
  4691. returns control to the AppleTalk Manager. The name that the routine places in
  4692. the buffer should be the name of the application that placed the entry in the
  4693. queue. The PATalkClosePrep function then calls each routine in the AppleTalk
  4694. Transition Queue a second time to inform it that the request to close the .MPP
  4695. driver has been canceled. If any routine in the AppleTalk Transition Queue
  4696. denies permission to close the .MPP driver, the PATalkClosePrep function returns
  4697. the result code closeErr.
  4698.  
  4699. If any routine denies permission to close the .MPP driver, the system displays a
  4700. dialog box informing the user that another application is using the .MPP driver,
  4701. and showing the name that the AppleTalk Transition Queue routine placed in the
  4702. buffer. The dialog box gives the user the option of canceling the request to
  4703. close AppleTalk, or of closing AppleTalk anyway. 
  4704.  
  4705. Note:  If the user chooses to close AppleTalk despite the fact that an
  4706. application is using it, the system calls the MPPClose function. AppleTalk calls
  4707. each application in the AppleTalk Transition Queue again, this time informing it
  4708. that AppleTalk is about to close. In this case, your AppleTalk Transition Queue
  4709. routine must prepare for the imminent closing of AppleTalk; it cannot deny
  4710. permission to the MPPClose function.
  4711.   
  4712. FUNCTION PATalkClosePrep (thePBptr: MPPPBPtr; async: BOOLEAN) : OSErr;
  4713.  
  4714. Parameter block
  4715.   Æ  26  csCode  word  always PATalkClosePrep
  4716.   Æ      appName  pointer  buffer for name of application that denies request
  4717.  
  4718. The PATalkClosePrep function calls each routine listed in the AppleTalk
  4719. Transition Queue to request permission to close the .MPP driver. 
  4720. The routine that calls the PATalkClosePrep function must allocate a 255-byte
  4721. buffer and provide a pointer to it in the appName parameter. If a routine in the
  4722. AppleTalk Transition Queue denies permission to close the .MPP driver, that
  4723. routine places a name in the buffer pointed to by the appName parameter, and the
  4724. AppleTalk Manager calls each routine in the AppleTalk Transition Queue a second
  4725. time to inform it that the request to close the .MPP driver has been canceled.
  4726. The PATalkClosePrep function then returns the result code closeErr, indicating
  4727. that the calling routine may not close the .MPP driver. The csCode parameter is
  4728. a routine selector; it is always equal to PATalkClosePrep for this function.
  4729.  
  4730. Result codes
  4731. noErr       0  no error
  4732. closeErr  –24  permission to close .MPP driver was denied
  4733.  
  4734. æKY PCancelATalkClosePrep
  4735. æFc AppleTalk.h
  4736. æT Function
  4737. æD 
  4738. pascal OSErr PCancelATalkClosePrep(MPPPBPtr thePBptr,Boolean async); 
  4739. æDT OSErr myVariable = PCancelATalkClosePrep((MPPPBPtr) thePBptr,(Boolean) async);
  4740. æRI VI
  4741. æC  
  4742. The system can use the PCancelATClosePrep function to undo the effects of the
  4743. PATalkClosePrep function. The system uses this function, for example, if some
  4744. condition prevents it from closing the .MPP driver even though each routine
  4745. listed in the AppleTalk Transition Queue gave permission to close it. When the
  4746. system calls the PCancelATClosePrep function, the AppleTalk Manager calls each
  4747. routine in the AppleTalk Transition Queue to inform it that the request to close
  4748. the .MPP driver has been canceled.
  4749.  
  4750. FUNCTION PCancelATClosePrep (thePBptr: MPPPBPtr; async: BOOLEAN) : OSErr;
  4751.  
  4752. Parameter block
  4753.   Æ  26  csCode  word  always PCancelATClosePrep 
  4754.  
  4755. The PCancelATClosePrep function undoes the effects of the PATalkClosePrep
  4756. function. The PCancelATClosePrep function calls each routine in the AppleTalk
  4757. Transition Queue to inform it that the request to close the .MPP driver has been
  4758. canceled. 
  4759.  
  4760. The operating system uses this function, for example, if some condition prevents
  4761. it from closing the .MPP driver even though each routine listed in the AppleTalk
  4762. Transition Queue gave permission to close it. 
  4763.  
  4764. The csCode parameter is a routine selector, always equal to PCancelATClosePrep
  4765. for this function.
  4766.  
  4767. Result codes
  4768. noErr  0  no error
  4769.  
  4770. æKY POpenATPSkt
  4771. æFc AppleTalk.h
  4772. æT Function
  4773. æD pascal OSErr POpenATPSkt(ATPPBPtr thePBptr,Boolean async); 
  4774. æDT OSErr myVariable = POpenATPSkt((ATPPBPtr) thePBptr,(Boolean) async);
  4775. æRI II-315,V-513
  4776. æC OpenATPSkt function
  4777.  
  4778. Parameter block
  4779.  
  4780.     ->  26 csCode         word          ;always openATPSkt
  4781.     <-> 28  atpSocket     byte          ;socket number
  4782.     ->  30  addrBlock     long word     ;socket request specification
  4783.  
  4784. OpenATPSkt opens a socket for the purpose of receiving requests.  ATPSocket 
  4785. contains the socket number of the socket to open.  If it's 0, a number is dynamically 
  4786. assigned and returned in atpSocket.  AddrBlock contains a specification of the 
  4787. socket addresses from which requests will be accepted.  A 0 in the network number, 
  4788. node ID, or socket number field of addrBlock means that requests will be accepted 
  4789. from every network, node, or socket, respectively.
  4790.  
  4791. Result codes    
  4792.  
  4793.       noErr             No error
  4794.       tooManySkts       Too many responding sockets
  4795.       noDataArea        Too many outstanding ATP calls
  4796.  
  4797. æKY PCloseATPSkt
  4798. æFc AppleTalk.h
  4799. æT Function
  4800. æD pascal OSErr PCloseATPSkt(ATPPBPtr thePBPtr,Boolean async); 
  4801. æDT OSErr myVariable = PCloseATPSkt((ATPPBPtr) thePBPtr,(Boolean) async);
  4802. æRI II-316,V-513
  4803. æC CloseATPSkt function
  4804.  
  4805. Parameter block
  4806.     ->  26  csCode      word    ;always closeATPSkt
  4807.     ->  28  atpSocket   byte    ;socket number
  4808.  
  4809. CloseATPSkt closes the socket whose number is specified by atpSocket, for the 
  4810. purpose of receiving requests.
  4811.  
  4812. Result codes    
  4813.    noErr      No error
  4814.  
  4815. æKY PSendRequest
  4816. æFc AppleTalk.h
  4817. æT Function
  4818. æD pascal OSErr PSendRequest(ATPPBPtr thePBPtr,Boolean async); 
  4819. æDT OSErr myVariable = PSendRequest((ATPPBPtr) thePBPtr,(Boolean) async);
  4820. æRI II-316,V-513
  4821. æC SendRequest function
  4822.  
  4823. Parameter block
  4824.  
  4825.     ->  18  userData           long word      ;user bytes
  4826.     <-  22  reqTID             word           ;transaction ID used in request
  4827.     ->  26  csCode             word           ;always sendRequest
  4828.     <-  28  currBitMap         byte           ;bit map
  4829.     <-> 29  atpFlags           byte           ;control information
  4830.     ->  30  addrBlock          long word      ;destination socket address
  4831.     ->  34 reqLength           word           ;request size in bytes
  4832.     ->  36 reqPointer          pointer        ;pointer to request data
  4833.     ->  40 bdsPointer          pointer        ;pointer to response BDS
  4834.     ->  44 numOfBuffs          byte           ;number of responses expected
  4835.     ->  45 timeOutVal          byte           ;timeout interval
  4836.     <-  46 numOfResps          byte           ;number of responses received
  4837.     <-> 47  retryCount         byte           ;number of retries
  4838.  
  4839. SendRequest sends a request to another socket and waits for a response.  UserData 
  4840. contains the four user bytes.  AddrBlock indicates the socket to which the request 
  4841. should be sent.  ReqLength and reqPointer contain the size and location of the 
  4842. request to send.  BDSPointer points to a response BDS where the responses are to be 
  4843. returned; numOfBuffs indicates the number of responses requested.  The number of 
  4844. responses received is returned in numOfResps.  If a nonzero value is returned in 
  4845. numOfResps, you can examine currBitMap to determine which packets of the 
  4846. transaction were actually received and to detect pieces for higher-level recovery, 
  4847. if desired.
  4848.  
  4849. TimeOutVal indicates the number of seconds that SendRequest should wait for a 
  4850. response before resending the request.  RetryCount indicates the maximum number 
  4851. of retries SendRequest should attempt.  The end-of-message flag of atpFlags will 
  4852. be set if the EOM bit is set in the last packet received in a valid response sequence.  
  4853. The exactly-once flag should be set if you want the request to be part of an 
  4854. exactly-once transaction.
  4855.  
  4856. To cancel a SendRequest call, you need the transaction ID; it's returned in reqTID.  
  4857. You can examine reqTID before the completion of the call, but its contents are valid 
  4858. only after the tidValid bit of atpFlags has been set.
  4859. SendRequest completes when either an entire response is received or the retry 
  4860. count is exceeded.
  4861.  
  4862. Note:  The value provided in retryCount will be modified during SendRequest 
  4863.        if any retries are made.  This field is used to monitor the number of retries; 
  4864.        for each retry, it's decremented by 1.
  4865.  
  4866. Result codes    
  4867.  
  4868.    noErr             No error
  4869.       reqFailed      Retry count exceeded
  4870.       tooManyReqs      Too many concurrent requests
  4871.       noDataArea        Too many outstanding ATP calls
  4872.       reqAborted        Request canceled by user
  4873.  
  4874. æKY PGetRequest
  4875. æFc AppleTalk.h
  4876. æT Function
  4877. æD pascal OSErr PGetRequest(ATPPBPtr thePBPtr,Boolean async); 
  4878. æDT OSErr myVariable = PGetRequest((ATPPBPtr) thePBPtr,(Boolean) async);
  4879. æRI II-317,V-513
  4880. æC GetRequest function
  4881.  
  4882. Parameter block
  4883.  
  4884.     <-   18 userData         long word     ;user bytes
  4885.     ->   26 csCode           word          ;always getRequest
  4886.     ->   28 atpSocket        byte          ;socket number
  4887.     <-   29 atpFlags         byte          ;control information
  4888.     <-   30 addrBlock        long word     ;source of request
  4889.     <->  34  reqLength       word          ;request buffer size
  4890.     ->   36 reqPointer       pointer       ;pointer to request buffer
  4891.     <-   44 bitMap           byte          ;bit map
  4892.     <-   46  transID         word          ;transaction ID
  4893.  
  4894. GetRequest sets up the mechanism to receive a request sent by a SendRequest call.  
  4895. UserData returns the four user bytes from the request.  ATPSocket contains the 
  4896. socket number of the socket that should listen for a request.  The internet address 
  4897. of the socket from which the request was sent is returned in addrBlock.  ReqLength 
  4898. and reqPointer indicate the size (in bytes) and location of a buffer to store the 
  4899. incoming request.  The actual size of the request is returned in reqLength.  The 
  4900. transaction bit map and transaction ID will be returned in bitMap and transID.  The 
  4901. exactly-once flag in atpFlags will be set if the request is part of an exactly-once 
  4902. transaction.
  4903.  
  4904. GetRequest completes when a request is received.
  4905.  
  4906. Result codes    
  4907.  
  4908.    noErr         No error
  4909.    badATPSkt     Bad responding socket
  4910.  
  4911. æKY PSendResponse
  4912. æFc AppleTalk.h
  4913. æT Function
  4914. æD pascal OSErr PSendResponse(ATPPBPtr thePBPtr,Boolean async); 
  4915. æDT OSErr myVariable = PSendResponse((ATPPBPtr) thePBPtr,(Boolean) async);
  4916. æRI II-317,V-513
  4917. æC SendResponse function
  4918.  
  4919. Parameter block
  4920.  
  4921.     <-  18  userData      long word     ;user bytes from TRel
  4922.     <-  22  reqTID        word          ;transaction ID used in request
  4923.     ->  26  csCode        word          ;always sendResponse
  4924.     ->  28  atpSocket     byte          ;socket number
  4925.     ->  29  atpFlags      byte          ;control information
  4926.     ->  30  addrBlock    long word      ;response destination
  4927.     ->  40  bdsPointer    pointer       ;pointer to response BDS 
  4928.     ->  44  numOfBuffs    byte          ;number of response packets being sent
  4929.     ->  45  bdsSize       byte          ;BDS size in elements
  4930.     ->  46  transID       word          ;transaction ID 
  4931.  
  4932. SendResponse sends a response to a socket.  If the response was part of an exactly-
  4933. once transaction, userData will contain the user bytes from the TRel packet.  
  4934. ATPSocket contains the socket number from which the response should be sent.  The 
  4935. end-of-message flag in atpFlags should be set if the response contains the final 
  4936. packet in a transaction composed of a group of packets and the number of responses 
  4937. is less than requested.  AddrBlock indicates the address of the socket to which the 
  4938. response should be sent.  BDSPointer points to a response BDS containing room for 
  4939. the maximum number of responses to be sent; bdsSize contains this maximum 
  4940. number.  NumOfBuffs contains the number of response packets to be sent in this 
  4941. call; you may wish to make AddResponse calls to complete the response.  TransID 
  4942. indicates the transaction ID of the associated request.
  4943.  
  4944. During exactly-once transactions, SendResponse doesn't complete until either a 
  4945. TRel packet is received from the socket that made the request, or the retry count is 
  4946. exceeded.
  4947.  
  4948. Result codes    
  4949.  
  4950.       noErr              No error
  4951.       badATPSkt          Bad responding socket
  4952.       noRelErr           No release received
  4953.       noDataArea         Too many outstanding ATP calls
  4954.       badBuffNum         Sequence number out of range
  4955.  
  4956. æKY PAddResponse
  4957. æFc AppleTalk.h
  4958. æT Function
  4959. æD pascal OSErr PAddResponse(ATPPBPtr thePBPtr,Boolean async); 
  4960. æDT OSErr myVariable = PAddResponse((ATPPBPtr) thePBPtr,(Boolean) async);
  4961. æRI II-318,V-513
  4962. æC AddResponse function
  4963.  
  4964. Parameter block
  4965.  
  4966.     ->  18  userData        long word   ;user bytes
  4967.     ->  26  csCode          word        ;always addResponse
  4968.     ->  28  atpSocket       byte        ;socket number
  4969.     ->  29  atpFlags        byte        ;control information
  4970.     ->  30  addrBlock       long word   ;response destination
  4971.     ->  34  reqLength       word        ;response size
  4972.     ->  36  reqPointer      pointer     ;pointer to response
  4973.     ->  44  rspNum          byte        ;sequence number
  4974.     ->  46  transID         word        ;transaction ID
  4975.  
  4976. AddResponse sends an additional response packet to a socket that has already been 
  4977. sent the initial part of a response via SendResponse.  UserData contains the four 
  4978. user bytes.  ATPSocket contains the socket number from which the response should 
  4979. be sent.  The end-of-message flag in atpFlags should be set if this response packet 
  4980. is the final packet in a transaction composed of a group of packets and the number 
  4981. of responses is less than requested.  AddrBlock indicates the socket to which the 
  4982. response should be sent.  ReqLength and reqPointer contain the size (in bytes) and 
  4983. location of the response to send; rspNum indicates the sequence number of the 
  4984. response (in the range 0 to 7).  TransID must contain the transaction ID.
  4985.  
  4986. Warning:  If the transaction is part of an exactly-once transaction, the buffer 
  4987.           used in the AddResponse call must not be altered or released until the 
  4988.           corresponding SendResponse call has completed. 
  4989.  
  4990. Result codes    
  4991.  
  4992.       noErr           No error
  4993.       badATPSkt       Bad responding socket
  4994.       noSendResp      AddResponse issued before SendResponse
  4995.       badBuffNum      Sequence number out of range
  4996.       noDataArea      Too many outstanding ATP calls
  4997.  
  4998. æKY PRelTCB
  4999. æFc AppleTalk.h
  5000. æT Function
  5001. æD pascal OSErr PRelTCB(ATPPBPtr thePBPtr,Boolean async); 
  5002. æDT OSErr myVariable = PRelTCB((ATPPBPtr) thePBPtr,(Boolean) async);
  5003. æRI II-319,V-513
  5004. æC RelTCB function
  5005.  
  5006. Parameter block
  5007.  
  5008.     ->  26  csCode        word           ;always relTCB
  5009.     ->  30  addrBlock     long word      ;destination of request
  5010.     ->  46  transID       word           ;transaction ID of request
  5011.  
  5012. RelTCB dequeues the specified SendRequest call and returns the result code 
  5013. reqAborted for the aborted call.  The transaction ID can be obtained from the reqTID 
  5014. field of the SendRequest queue entry; see the description of SendRequest for details.
  5015.  
  5016. Result codes    
  5017.  
  5018.    noErr            No error
  5019.    cbNotFound       ATP control block not found
  5020.    noDataArea       Too many outstanding ATP calls
  5021.  
  5022. æKY PRelRspCB
  5023. æFc AppleTalk.h
  5024. æT Function
  5025. æD pascal OSErr PRelRspCB(ATPPBPtr thePBPtr,Boolean async); 
  5026. æDT OSErr myVariable = PRelRspCB((ATPPBPtr) thePBPtr,(Boolean) async);
  5027. æRI II-319,V-514
  5028. æC RelRspCB function
  5029.  
  5030. Parameter block
  5031.  
  5032.     ->  26  csCode        word          ;always relRspCB
  5033.     ->  28  atpSocket     byte          ;socket number that request was received on
  5034.     ->  30  addrBlock     long word     ;source of request
  5035.     ->  46  transID       word          ;transaction ID of request
  5036.  
  5037. In an exactly-once transaction, RelRspCB cancels the specified SendResponse, 
  5038. without waiting for the release timer to expire or a TRel packet to be received.  No 
  5039. error is returned for the SendResponse call.  Whan called to cancel a transaction 
  5040. that isn't using exactly-once service, RelRspCB returns cbNotFound.  The 
  5041. transaction ID can be obtained from the reqTID field of the SendResponse queue 
  5042. entry; see the description of SendResponse for details.
  5043.  
  5044. Result codes    
  5045.  
  5046.    noErr            No error
  5047.    cbNotFound       ATP control block not found
  5048.  
  5049. æKY PNSendRequest
  5050. æFc AppleTalk.h
  5051. æT Function
  5052. æD pascal OSErr PNSendRequest(ATPPBPtr thePBPtr,Boolean async); 
  5053. æDT OSErr myVariable = PNSendRequest((ATPPBPtr) thePBPtr,(Boolean) async);
  5054. æRI V-516
  5055. æC  
  5056. »Sending an ATP Request Through a Specified Socket
  5057.  
  5058. ATP requests can now be sent through client-specified sockets.  ATP previously would
  5059. open a dynamic socket, send the request through it, and close the socket when the
  5060. request was completed.  The client can now choose to send a request through an already-opened
  5061. socket; this also allows more than one request to be sent per socket.   A new call,
  5062. PNSendRequest, has been added for this purpose.  The function of the old SendRequest
  5063. call itself remains unchanged.
  5064.  
  5065. FUNCTION PNSendRequest (thePBptr: ATPBPtr; async: BOOLEAN) : OSErr;
  5066.  
  5067. Parameter block
  5068.   -->    18    userData     longword  User bytes
  5069.   <--    22    reqTID       word      Transaction ID used in request
  5070.   -->    26    csCode       word      Always sendRequest
  5071.   <->    28    atpSocket    byte      Socket to send request on
  5072.                                        or current bitmap
  5073.   <->    29    atpFlags     byte      Control information
  5074.   -->    30    addrBlock    longword  Destination socket address
  5075.   -->    34    reqLength    word      Request size in bytes
  5076.   -->    36    reqPointer   pointer   Pointer to request data
  5077.   -->    40    bdsPointer   pointer   Pointer to response BDS
  5078.   -->    44    numOfBuffs   byte      Number of responses expected
  5079.   -->    45    timeOutVal   byte      Timeout interval
  5080.   <--    46    numOf Resps  byte      Number of responses received
  5081.   <->    47    retryCount   byte      Number of retries
  5082.   <--    48    intBuff      word      Used internally
  5083.  
  5084. The PNSendRequest call is functionally equivalent to the SendRequest call, however
  5085. PNSendRequest allows you to specify, in the atpSocket field, the socket through which
  5086. the request is to be sent.  This socket must have been previously opened through an
  5087. OpenATPSkt request (otherwise a badATPSkt error will be returned).  Note that PNSendRequest
  5088. requires two additional bytes of memory at the end of the parameter block, immediately
  5089. following the retryCount.  These bytes are for the internal use of the AppleTalk
  5090. Manager and should not be modified while the PNSendRequest call is active.
  5091.  
  5092. There is a machine-dependent limit as to the number of concurrent PNSendRequests that
  5093. can be active on a given socket.  If this limit is exceeded, the error tooManyReqs is
  5094. returned.
  5095.  
  5096. One additional difference between SendRequest and PNSendRequest is that a PNSendRequest
  5097. can only be aborted by a PKillSendReq call (see below), whereas a SendRequest can be
  5098. aborted by either a RelTCB or KillSendReq call.
  5099.  
  5100. Result Codes    noErr          No error
  5101.                 reqFailed      Retry count exceeded
  5102.                 tooManyReqs    Too many concurrent requests
  5103.                 noDataArea     Too many outstanding ATP calls
  5104.                 reqAborted     Request cancelled by user
  5105.  
  5106. æKY PKillSendReq
  5107. æFc AppleTalk.h
  5108. æT Function
  5109. æD pascal OSErr PKillSendReq(ATPPBPtr thePBPtr,Boolean async); 
  5110. æDT OSErr myVariable = PKillSendReq((ATPPBPtr) thePBPtr,(Boolean) async);
  5111. æRI V-517
  5112. æC  
  5113. »Aborting ATP SendRequests
  5114.  
  5115. The  RelTCB call is still supported, but only for aborting SendRequests.  To abort
  5116. PNSendRequests, a new call, PKillSendReq, has been added.  This call will abort both
  5117. SendRequests and PNSendRequests.  PKillSendReq’s only argument is the queue element
  5118. pointer of the request to be aborted.  The queue element pointer is passed at the
  5119. offset of the PKillSendReq queue element specified by aKillQE1.
  5120.  
  5121. FUNCTION PKillSendReq (thePBptr: ATPPBPtr; async: BOOLEAN) : OSErr;
  5122.  
  5123. Parameter block
  5124.   -->    26    csCode    word     Always PKillSendReq
  5125.   -->    44    aKillQEl  pointer  Pointer to queue element
  5126.  
  5127. PKillSendReq is functionally equivalent to RelTCB, except that it takes different
  5128. arguments and will abort both SendRequests and PNSendRequests.  To abort one of these
  5129. calls, place a pointer to the queue element of the call to abort in aKillQEl and
  5130. issue the PKillSendReq call.
  5131.  
  5132. Result Codes    noErr          No error
  5133.                 cbNotFound     aKillQEl does not point to a SendReq
  5134.                                or NSendReq queue element
  5135.  
  5136. æKY PKillGetReq
  5137. æFc AppleTalk.h
  5138. æT Function
  5139. æD pascal OSErr PKillGetReq(ATPPBPtr thePBPtr,Boolean async); 
  5140. æDT OSErr myVariable = PKillGetReq((ATPPBPtr) thePBPtr,(Boolean) async);
  5141. æRI V-518
  5142. æC  
  5143. »Aborting ATP GetRequests
  5144.  
  5145. ATP GetRequests can now be aborted through the PKillGetReq call.  This call looks and
  5146. works just like the PKillSendReq call, and is used to abort a specific GetRequest
  5147. call.  Previously it was necessary to close the socket  to abort all GetRequest calls
  5148. on the socket.
  5149.  
  5150. FUNCTION PKillGetReq (thePBptr: ATPPBPtr; async: BOOLEAN) : OSErr;
  5151.  
  5152. Parameter block
  5153.   -->    26    csCode    word     Always PKillGetReq
  5154.   -->    44    aKillQEl  pointer  Pointer to queue element
  5155.  
  5156. PKillGetReq will abort a specific outstanding GetRequest call (as opposed to closing
  5157. the socket, which aborts all outstanding GetRequests on that socket).  The call will
  5158. be completed with a reqAborted error.  To abort a GetRequest, place a pointer to the
  5159. queue element of the call to abort in aKillQEl and issue the PKillGetReq call.
  5160.  
  5161. Result Codes    noErr         No error
  5162.                 cbNotFound    aKillQEl does not point to a GetReq
  5163.                               queue element
  5164.  
  5165. æKY PKillAllGetReq
  5166. æFc AppleTalk.h
  5167. æT Function
  5168. æD 
  5169. pascal OSErr PKillAllGetReq(ATPPBPtr thePBPtr,Boolean async); 
  5170. æDT OSErr myVariable = PKillAllGetReq((ATPPBPtr) thePBPtr,(Boolean) async);
  5171. æRI V-518
  5172. æC  
  5173. »Aborting ATP GetRequests
  5174.  
  5175. ATP GetRequests can now be aborted through the PKillGetReq call.  This call looks and
  5176. works just like the PKillSendReq call, and is used to abort a specific GetRequest
  5177. call.  Previously it was necessary to close the socket  to abort all GetRequest calls
  5178. on the socket.
  5179.  
  5180. FUNCTION PKillGetReq (thePBptr: ATPPBPtr; async: BOOLEAN) : OSErr;
  5181.  
  5182. Parameter block
  5183.   -->    26    csCode    word     Always PKillGetReq
  5184.   -->    44    aKillQEl  pointer  Pointer to queue element
  5185.  
  5186. PKillGetReq will abort a specific outstanding GetRequest call (as opposed to closing
  5187. the socket, which aborts all outstanding GetRequests on that socket).  The call will
  5188. be completed with a reqAborted error.  To abort a GetRequest, place a pointer to the
  5189. queue element of the call to abort in aKillQEl and issue the PKillGetReq call.
  5190.  
  5191. Result Codes    noErr         No error
  5192.                 cbNotFound    aKillQEl does not point to a GetReq
  5193.                               queue element
  5194.  
  5195. æKY BuildLAPwds
  5196. æFc AppleTalk.h
  5197. æT Function
  5198. æD pascal void BuildLAPwds(Ptr wdsPtr,Ptr dataPtr,short destHost,short prototype,
  5199.     short frameLen); 
  5200. æDT BuildLAPwds((Ptr) wdsPtr,(Ptr) dataPtr,(short) destHost,(short) prototype,()
  5201.     short frameLen);
  5202. æRI V-514
  5203. æC 
  5204. This routine builds a single-frame write data structure LAP WDS for use with the
  5205. PWriteLAP call.  Given a buffer of length frameLen pointed to by dataPtr, it fills in
  5206. the WDS pointed to by wdsPtr and sets the destination node and protocol type as
  5207. indicated by destHost and protoType, respectively.  The WDS indicated must contain at
  5208. least two elements.
  5209.  
  5210. æKY BuildDDPwds
  5211. æFc AppleTalk.h
  5212. æT Function
  5213. æD pascal void BuildDDPwds(Ptr wdsPtr,Ptr headerPtr,Ptr dataPtr,const AddrBlock netAddr,
  5214.     short ddpType,short dataLen); 
  5215. æDT BuildDDPwds((Ptr) wdsPtr,(Ptr) headerPtr,(Ptr) dataPtr,(const AddrBlock) netAddr,()
  5216.     short ddpType,(short) dataLen);
  5217. æRI V-514
  5218. æC 
  5219. This routine builds a single-frame write data structure  DDP WDS, for use with the
  5220. PWriteDDP call.  Given a header buffer of at least 17 bytes pointed to by headerPtr
  5221. and a data buffer of length dataLen pointed to by dataPtr, it fills in the WDS pointed
  5222. to by wdsPtr, and sets the destination address and protocol type as indicated by
  5223. destaddress and DDPtype, respectively.  The WDS indicated must contain at least 3
  5224. elements.
  5225.  
  5226. æKY NBPSetEntity
  5227. æFc AppleTalk.h
  5228. æT Function
  5229. æD pascal void NBPSetEntity(Ptr buffer,Ptr nbpObject,Ptr nbpType,Ptr nbpZone); 
  5230. æDT NBPSetEntity((Ptr) buffer,(Ptr) nbpObject,(Ptr) nbpType,(Ptr) nbpZone);
  5231. æRI V-514
  5232. æC 
  5233. This routine builds an NBP entity structure, for use with the PLookupNBP and PConfirmName
  5234. calls.  Given a buffer of at least the size of the EntityName data structure (99
  5235. bytes) pointed to by buffer, this routine sets the indicated object, type, and zone
  5236. in that buffer.
  5237.  
  5238. æKY NBPSetNTE
  5239. æFc AppleTalk.h
  5240. æT Function
  5241. æD pascal void NBPSetNTE(Ptr ntePtr,Ptr nbpObject,Ptr nbpType,Ptr nbpZone,
  5242.     short socket); 
  5243. æDT NBPSetNTE((Ptr) ntePtr,(Ptr) nbpObject,(Ptr) nbpType,(Ptr) nbpZone,()
  5244.     short socket);
  5245. æRI V-515
  5246. æC 
  5247. This routine builds an NBP names table entry, for use with the PRegisterName call. 
  5248. Given a names table entry of at least the size of the EntityName data structure plus
  5249. nine bytes (108 bytes) pointed to by ntePtr, this routine sets the indicated object,
  5250. type, zone, and socket in that names table entry.
  5251.  
  5252. æKY GetBridgeAddress
  5253. æFc AppleTalk.h
  5254. æT Function
  5255. æD pascal short GetBridgeAddress(void); 
  5256. æDT short myVariable = GetBridgeAddress()(void);
  5257. æRT 132
  5258. æRI V-515, N132-2
  5259. æC 
  5260. This routine returns the current address of a bridge in the low byte, or zero if
  5261. there is none.
  5262.  
  5263. æKY BuildBDS
  5264. æFc AppleTalk.h
  5265. æT Function
  5266. æD pascal short BuildBDS(Ptr buffPtr,Ptr bdsPtr,short buffSize); 
  5267. æDT short myVariable = BuildBDS((Ptr) buffPtr,(Ptr) bdsPtr,(short) buffSize);
  5268. æRI V-515
  5269. æC 
  5270. This routine builds a BDS, for use with the ATP calls.  Given a data buffer of length
  5271. buffSize pointed to by buffPtr, it fills in the BDS pointed to by bdsPtr.  The buffer
  5272. will be broken up into pieces of maximum size (578 bytes).  The user bytes in the BDS
  5273. are not modified by this routine.  This routine is provided only as a convenience;
  5274. generally the caller will be able to build the BDS completely from Pascal without
  5275. it.
  5276.  
  5277. æKY MPPOpen
  5278. æFc AppleTalk.h
  5279. æT Function
  5280. æD pascal OSErr MPPOpen(void); 
  5281. æDT OSErr myVariable = MPPOpen()(void);
  5282. æMM
  5283. æRT 224
  5284. æRI II-275
  5285. æC 
  5286. MPPOpen first checks whether the .MPP driver has already been loaded; if it has,
  5287. MPPOpen does nothing and returns noErr. If MPP hasn’t been loaded, MPPOpen attempts
  5288. to load it into the system heap. If it succeeds, it then initializes the driver’s
  5289. variables and goes through the process of dynamically assigning a node ID to that
  5290. Macintosh. On a Macintosh 512K or XL, it also loads the .ATP driver and NBP code into
  5291. the system heap.
  5292.  
  5293. If serial port B isn’t configured for AppleTalk, or is already in use, the .MPP
  5294. driver isn’t loaded and an appropriate result code is returned.
  5295.  
  5296. Result codes    noErr        No error
  5297.                 portInUse    Port B is already in use
  5298.                 portNotCf    Port B not configured for AppleTalk
  5299.  
  5300. æKY MPPClose
  5301. æFc AppleTalk.h
  5302. æT Function
  5303. æD pascal OSErr MPPClose(void); 
  5304. æDT OSErr myVariable = MPPClose()(void);
  5305. æMM
  5306. æRI II-275
  5307. æC 
  5308. MPPClose removes the .MPP driver, and any data structures associated with it, from
  5309. memory. If the .ATP driver or NBP code were also installed, they’re removed as well.
  5310. MPPClose also returns the use of port B to the Serial Driver.
  5311.  
  5312. Warning:  Since other co-resident programs may be using AppleTalk, it’s
  5313.           strongly recommended that you never use this call. MPPClose will
  5314.           completely disable AppleTalk; the only way to restore AppleTalk
  5315.           is to call MPPOpen again.
  5316.  
  5317. æKY LAPOpenProtocol
  5318. æFc AppleTalk.h
  5319. æT Function
  5320. æD pascal OSErr LAPOpenProtocol(ABByte theLAPType,Ptr protoPtr); 
  5321. æDT OSErr myVariable = LAPOpenProtocol((ABByte) theLAPType,(Ptr) protoPtr);
  5322. æMM
  5323. æRI II-277
  5324. æC 
  5325. LAPOpenProtocol adds the ALAP protocol type specified by theLAPType to the
  5326. node’s protocol table. If you provide a pointer to a protocol handler in protoPtr,
  5327. ALAP will send each frame with an ALAP protocol type of theLAPType to that protocol
  5328. handler.
  5329.  
  5330. If protoPtr is NIL, the default protocol handler will be used for receiving frames
  5331. with an ALAP protocol type of theLAPType. In this case, to receive a frame you must
  5332. call LAPRead to provide the default protocol handler with a buffer for placing the
  5333. data. If, however, you’ve written your own protocol handler and protoPtr points to
  5334. it, your protocol handler will have the responsibility for receiving the frame and
  5335. it’s not necessary to call LAPRead.
  5336.  
  5337. Result codes    noErr         No error
  5338.                 lapProtErr    Error attaching protocol type
  5339.  
  5340. æKY LAPCloseProtocol
  5341. æFc AppleTalk.h
  5342. æT Function
  5343. æD pascal OSErr LAPCloseProtocol(ABByte theLAPType); 
  5344. æDT OSErr myVariable = LAPCloseProtocol((ABByte) theLAPType);
  5345. æMM
  5346. æRI II-277
  5347. æC 
  5348. LAPCloseProtocol removes from the node’s protocol table the specified ALAP protocol
  5349. type, as well as its protocol handler.
  5350.  
  5351. Warning:  Don’t close ALAP protocol type values 1 or 2. If you close these
  5352.           protocol types, DDP will be disabled; once disabled, the only way
  5353.           to restore DDP is to restart the system, or to close and then
  5354.           reopen AppleTalk.
  5355.  
  5356. Result codes    noErr         No error
  5357.                 lapProtErr    Error detaching protocol type
  5358.  
  5359. æKY LAPWrite
  5360. æFc AppleTalk.h
  5361. æT Function
  5362. æD pascal OSErr LAPWrite(ATLAPRecHandle abRecord,Boolean async); 
  5363. æDT OSErr myVariable = LAPWrite((ATLAPRecHandle) abRecord,(Boolean) async);
  5364. æMM
  5365. æRI II-277
  5366. æC 
  5367. ABusRecord
  5368.   <--    abOpcode                {always tLAPWrite}
  5369.   <--    abResult                {result code}
  5370.   -->    abUserReference         {for your use}
  5371.   -->    lapAddress.dstNodeID    {destination node ID}
  5372.   -->    lapAddress.lapProtType  {ALAP protocol type}
  5373.   -->    lapReqCount             {length of frame data}
  5374.   -->    lapDataPtr              {pointer to frame data}
  5375.  
  5376. LAPWrite sends a frame to another node. LAPReqCount and lapDataPtr specify the length
  5377. and location of the data to send. The lapAddress.lapProtType field indicates the ALAP
  5378. protocol type of the frame and the lapAddress.dstNodeID indicates the node ID of the
  5379. node to which the frame should be sent.
  5380.  
  5381. Note:  The first two bytes of an ALAP frame’s data must contain the length
  5382.        in bytes of that data, including the length bytes themselves.
  5383.  
  5384. Result codes    noErr            No error
  5385.                 excessCollsns    Unable to contact destination node;
  5386.                                  packet not sent
  5387.                 ddpLenErr        ALAP data length too big
  5388.                 lapProtErr       Invalid ALAP protocol type
  5389.  
  5390. æKY LAPRead
  5391. æFc AppleTalk.h
  5392. æT Function
  5393. æD pascal OSErr LAPRead(ATLAPRecHandle abRecord,Boolean async); 
  5394. æDT OSErr myVariable = LAPRead((ATLAPRecHandle) abRecord,(Boolean) async);
  5395. æMM
  5396. æRI II-278
  5397. æC  
  5398. ABusRecord
  5399.   <--    abOpcode                {always tLAPRead}
  5400.   <--    abResult                {result code}
  5401.   -->    abUserReference         {for your use}
  5402.   <--    lapAddress.dstNodeID    {destination node ID}
  5403.   <--    lapAddress.srcNodeID    {source node ID}
  5404.   -->    lapAddress.lapProtType  {ALAP protocol type}
  5405.   -->    lapReqCount             {buffer size in bytes}
  5406.   <--    lapActCount             {number of frame data bytes actually received}
  5407.   -->    lapDataPtr              {pointer to buffer}
  5408.  
  5409. LAPRead receives a frame from another node. LAPReqCount and lapDataPtr specify the
  5410. size and location of the buffer that will receive the frame data. If the buffer isn’t
  5411. large enough to hold all of the incoming frame data, the extra bytes will be discarded
  5412. and buf2SmallErr will be returned. The number of bytes actually received is returned
  5413. in lapActCount. Only frames with ALAP protocol type equal to lapAddress.lapProtType
  5414. will be received. The node IDs of the frame’s source and destination nodes are returned
  5415. in lapAddress.srcNodeID and lapAddress.dstNodeID. You can determine whether the
  5416. packet was broadcast to you by examining the value of lapAddress.dstNodeID—if the
  5417. packet was broadcast it’s equal to 255, otherwise it’s equal to your node ID.
  5418.  
  5419. Note:  You should issue LAPRead calls only for ALAP protocol types that were
  5420.        opened (via LAPOpenProtocol) to use the default protocol handler.
  5421.  
  5422. Warning:  If you close a protocol type for which there are still LAPRead
  5423.           calls pending, the calls will be canceled but the memory occupied
  5424.           by their ABusRecords will not be released. For this reason, before
  5425.           closing a protocol type, call LAPRdCancel to cancel any pending
  5426.           LAPRead calls associated with that protocol type.
  5427.  
  5428. Result codes    noErr           No error
  5429.                 buf2SmallErr    Frame too large for buffer
  5430.                 readQErr        Invalid protocol type or protocol type not
  5431.                                 found in table
  5432.  
  5433. æKY LAPRdCancel
  5434. æFc AppleTalk.h
  5435. æT Function
  5436. æD pascal OSErr LAPRdCancel(ATLAPRecHandle abRecord); 
  5437. æDT OSErr myVariable = LAPRdCancel((ATLAPRecHandle) abRecord);
  5438. æMM
  5439. æRI II-279
  5440. æC 
  5441. Given the handle to the ABusRecord of a previously made LAPRead call, LAPRdCancel
  5442. dequeues the LAPRead call, provided that a packet satisfying the LAPRead has not
  5443. already arrived. LAPRdCancel returns noErr if the LAPRead call is successfully removed
  5444. from the queue. If LAPRdCancel returns recNotFnd, check the abResult field to verify
  5445. that the LAPRead has been completed and determine its outcome.
  5446.  
  5447. Result codes    noErr        No error
  5448.                 readQErr     Invalid protocol type or protocol type not
  5449.                              found in table
  5450.                 recNotFnd    ABRecord not found in queue
  5451.  
  5452. »Example
  5453.  
  5454. This example sends an ALAP packet synchronously and waits asynchronously for a response.
  5455. Assume that both nodes are using a known protocol type (in this case, 73) to receive
  5456. packets, and that the destination node has a node ID of 4.
  5457.  
  5458. VAR
  5459.   myABRecord: ABRecHandle;
  5460.   myBuffer: PACKED ARRAY [0..599] OF CHAR; {buffer for both send and receive}
  5461.   myLAPType: Byte;
  5462.   errCode, index, dataLen: INTEGER;
  5463.   someText: Str255;
  5464.   async: BOOLEAN;
  5465.  
  5466. BEGIN
  5467.   errCode := MPPOpen;
  5468.   IF errCode <> noErr THEN
  5469.     WRITELN('Error in opening AppleTalk')
  5470.     {Maybe serial port B isn't available for use by AppleTalk}
  5471.   ELSE
  5472.     BEGIN
  5473.     {Call Memory Manager to allocate ABusRecord}
  5474.     myABRecord := ABRecHandle(NewHandle(lapSize));
  5475.     myLAPType := 73;
  5476.    {Enter myLAPType into protocol handler table and install default handler to }
  5477.     { service frames of that ALAP type. No packets of that ALAP type will be }
  5478.     { received until we call LAPRead.}
  5479.     errCode := LAPOpenProtocol(myLAPType, NIL);
  5480.     IF errCode <> noErr THEN
  5481.       WRITELN('Error while opening the protocol type')
  5482.       {Have we opened too many protocol types? Remember that DDP uses two of }
  5483.       { them.}
  5484.     ELSE
  5485.       BEGIN
  5486.       {Prepare data to be sent}
  5487.       someText := 'This data will be in the ALAP data area';
  5488.       {The .MPP implementation requires that the first two bytes of the ALAP }
  5489.       { data field contain the length of the data, including the length bytes }
  5490.       { themselves.}
  5491.       dataLen := LENGTH(someText) + 2;
  5492.       buffer[0] := CHR(dataLen DIV 256); {high byte of data length}
  5493.       buffer[1] := CHR(dataLen MOD 256); {low byte of data length}
  5494.       FOR index := 1 TO dataLen - 2 DO {stuff buffer with packet data}
  5495.         buffer[index + 1] := someText[index];
  5496.       async := FALSE;
  5497.       WITH myABRecord^^ DO {fill parameters in the ABusRecord}
  5498.         BEGIN
  5499.         lapAddress.lapProtType := myLAPType;
  5500.         lapAddress.dstNodeID := 4;
  5501.         lapReqCount := dataLen;
  5502.         lapDataPtr := @buffer;
  5503.         END;
  5504.       {Send the frame}
  5505.       errCode := LAPWrite(myABRecord, async);
  5506.       {In the case of a sync call, errCode and the abResult field of }
  5507.       { the myABRecord will contain the same result code. We can also }
  5508.       { reuse myABRecord, since we know whether the call has completed.}
  5509.       IF errCode <> noErr THEN
  5510.         WRITELN('Error while writing out the packet')
  5511.         {Maybe the receiving node wasn't on-line}
  5512.       ELSE
  5513.         BEGIN
  5514.         {We have sent out the packet and are now waiting for a response. We }
  5515.         { issue an async LAPRead call so that we don't “hang” waiting for a }
  5516.         { response that may not come.}
  5517.         async := TRUE;
  5518.         WITH myABRecord^^ DO
  5519.           BEGIN
  5520.           lapAddress.lapProtType := myLAPType;
  5521.           {ALAP type we want to receive }
  5522.           lapReqCount := 600; {our buffer is maximum size}
  5523.           lapDataPtr := @buffer;
  5524.           END;
  5525.         errCode := LAPRead(myABRecord, async); {wait for a packet}
  5526.         IF errCode <> noErr THEN
  5527.           WRITELN('Error while trying to queue up a LAPRead')
  5528.           {Was the protocol handler installed correctly?}
  5529.         ELSE
  5530.           BEGIN
  5531.           {We can either sit here in a loop and poll the abResult }
  5532.           { field or just exit our code and use the event }
  5533.           { mechanism to flag us when the packet arrives.}
  5534.           CheckForMyEvent; {your procedure for checking for a network event}
  5535.           errCode := LAPCloseProtocol(myLAPType);
  5536.           IF errCode <> noErr THEN
  5537.             WRITELN('Error while closing the protocol type');
  5538.           END;
  5539.         END;
  5540.       END;
  5541.     END;
  5542. END.
  5543.  
  5544. æKY DDPOpenSocket
  5545. æFc AppleTalk.h
  5546. æT Function
  5547. æD pascal OSErr DDPOpenSocket(short *theSocket,Ptr sktListener); 
  5548. æDT OSErr myVariable = DDPOpenSocket((short *) theSocket,(Ptr) sktListener);
  5549. æMM
  5550. æRI II-282
  5551. æC 
  5552. DDPOpenSocket adds a socket and its socket listener to the socket table. If theSocket
  5553. is nonzero, it must be in the range 64 to 127, and it specifies the socket’s number;
  5554. if theSocket is 0, DDPOpenSocket dynamically assigns a socket number in the range 128
  5555. to 254, and returns it in theSocket. SktListener contains a pointer to the socket
  5556. listener; if it’s NIL, the default listener will be used.
  5557.  
  5558. If you’re using the default socket listener, you must then call DDPRead to receive a
  5559. datagram (in order to specify buffer space for the default socket listener). If,
  5560. however, you’ve written your own socket listener and sktListener points to it, your
  5561. listener will provide buffers for receiving datagrams and you shouldn’t use DDPRead
  5562. calls.
  5563.  
  5564. DDPOpenSocket will return ddpSktErr if you pass the number of an already opened
  5565. socket, if you pass a socket number greater than 127, or if the socket table is
  5566. full.
  5567.  
  5568. Note:  The range of static socket numbers 1 through 63 is reserved by Apple
  5569.        for internal use. Socket numbers 64 through 127 are available for
  5570.        unrestricted experimental use.
  5571.  
  5572. Result codes    noErr        No error
  5573.                 ddpSktErr    Socket error
  5574.  
  5575. æKY DDPCloseSocket
  5576. æFc AppleTalk.h
  5577. æT Function
  5578. æD pascal OSErr DDPCloseSocket(short theSocket); 
  5579. æDT OSErr myVariable = DDPCloseSocket((short) theSocket);
  5580. æMM
  5581. æRI II-282
  5582. æC 
  5583. DDPCloseSocket removes the entry of the specified socket from the socket table and
  5584. cancels all pending DDPRead calls that have been made for that socket. If you pass a
  5585. socket number of 0, or if you attempt to close a socket that isn’t open, DDPCloseSocket
  5586. will return ddpSktErr.
  5587.  
  5588. Result codes    noErr        No error
  5589.                 ddpSktErr    Socket error
  5590.  
  5591. æKY DDPRead
  5592. æFc AppleTalk.h
  5593. æT Function
  5594. æD pascal OSErr DDPRead(ATDDPRecHandle abRecord,Boolean retCksumErrs,Boolean async); 
  5595. æDT OSErr myVariable = DDPRead((ATDDPRecHandle) abRecord,(Boolean) retCksumErrs,(Boolean) async);
  5596. æMM
  5597. æRI II-283
  5598. æC 
  5599. ABusRecord
  5600.   <--    abOpcode         {always tDDPRead}
  5601.   <--    abResult         {result code}
  5602.   -->    abUserReference  {for your use}
  5603.   <--    ddpType          {DDP protocol type}
  5604.   -->    ddpSocket        {listening socket number}
  5605.   <--    ddpAddress       {source socket address}
  5606.   -->    ddpReqCount      {buffer size in bytes}
  5607.   <--    ddpActCount      {number of bytes actually received}
  5608.   -->    ddpDataPtr       {pointer to buffer}
  5609.   <--    ddpNodeID        {original destination node ID}
  5610.  
  5611. DDPRead receives a datagram from another socket. The size and location of the buffer
  5612. that will receive the data are specified by ddpReqCount and ddpDataPtr. If the buffer
  5613. isn’t large enough to hold all of the incoming frame data, the extra bytes will be
  5614. discarded and buf2SmallErr will be returned. The number of bytes actually received is
  5615. returned in ddpActCount. DDPSocket specifies the socket to receive the datagram (the
  5616. “listening” socket). The node to which the packet was sent is returned in ddpNodeID;
  5617. if the packet was broadcast ddpNodeID will contain 255. The address of the socket
  5618. that sent the packet is returned in ddpAddress. If retCksumErrs is FALSE, DDPRead
  5619. will discard any packets received with an invalid checksum and inform the caller of
  5620. the error. If retCksumErrs is TRUE, DDPRead will deliver all packets, whether or not
  5621. the checksum is valid; it will also notify the caller when there’s a checksum error.
  5622.  
  5623. Note:  The sender of the datagram must be in a different node from the
  5624.        receiver. You should issue DDPRead calls only for receiving datagrams
  5625.        for sockets opened with the default socket listener; see the
  5626.        description of DDPOpenSocket.
  5627.  
  5628. Note:  If the buffer provided isn’t large enough to hold all of the incoming
  5629.        frame data (buf2SmallErr), the checksum can’t be calculated; in this
  5630.        case, DDPRead will deliver packets even if retCksumErrs is FALSE.
  5631.  
  5632. Result codes    noErr           No error
  5633.                 buf2SmallErr    Datagram too large for buffer
  5634.                 cksumErr        Checksum error
  5635.                 ddpLenErr       Datagram length too big
  5636.                 ddpSktErr       Socket error
  5637.                 readQErr        Invalid socket or socket not found in table
  5638.  
  5639. æKY DDPWrite
  5640. æFc AppleTalk.h
  5641. æT Function
  5642. æD pascal OSErr DDPWrite(ATDDPRecHandle abRecord,Boolean doChecksum,Boolean async); 
  5643. æDT OSErr myVariable = DDPWrite((ATDDPRecHandle) abRecord,(Boolean) doChecksum,(Boolean) async);
  5644. æMM
  5645. æRI II-283
  5646. æC  
  5647. ABusRecord
  5648.   <--    abOpcode         {always tDDPWrite}
  5649.   <--    abResult         {result code}
  5650.   -->    abUserReference  {for your use}
  5651.   -->    ddpType          {DDP protocol type}
  5652.   -->    ddpSocket        {source socket number}
  5653.   -->    ddpAddress       {destination socket address}
  5654.   -->    ddpReqCount      {length of datagram data}
  5655.   -->    ddpDataPtr       {pointer to buffer}
  5656.  
  5657. DDPWrite sends a datagram to another socket. DDPReqCount and ddpDataPtr specify the
  5658. length and location of the data to send. The ddpType field indicates the DDP protocol
  5659. type of the frame, and ddpAddress is the complete internet address of the socket to
  5660. which the datagram should be sent. DDPSocket specifies the socket from which the
  5661. datagram should be sent. Datagrams sent over the internet to a node on an AppleTalk
  5662. network different from the sending node’s network have an optional software checksum
  5663. to detect errors that might occur inside the intermediate bridges. If doChecksum is
  5664. TRUE, DDPWrite will compute this checksum; if it’s FALSE, this software checksum
  5665. feature is ignored.
  5666.  
  5667. Note:  The destination socket can’t be in the same node as the program
  5668.        making the DDPWrite call.
  5669.  
  5670. Result codes    noErr          No error
  5671.                 ddpLenErr      Datagram length too big
  5672.                 ddpSktErr      Source socket not open
  5673.                 noBridgeErr    No bridge found
  5674.  
  5675. æKY DDPRdCancel
  5676. æFc AppleTalk.h
  5677. æT Function
  5678. æD pascal OSErr DDPRdCancel(ATDDPRecHandle abRecord); 
  5679. æDT OSErr myVariable = DDPRdCancel((ATDDPRecHandle) abRecord);
  5680. æMM
  5681. æRI II-284
  5682. æC 
  5683. Given the handle to the ABusRecord of a previously made DDPRead call, DDPRdCancel
  5684. dequeues the DDPRead call, provided that a packet satisfying the DDPRead hasn’t
  5685. already arrived. DDPRdCancel returns noErr if the DDPRead call is successfully removed
  5686. from the queue. If DDPRdCancel returns recNotFnd, check the abResult field of abRecord
  5687. to verify that the DDPRead has been completed and determine its outcome.
  5688.  
  5689. Result codes    noErr        No error
  5690.                 readQErr     Invalid socket or socket not found in table
  5691.                 recNotFnd    ABRecord not found in queue
  5692.  
  5693. »Example
  5694.  
  5695. This example sends a DDP packet synchronously and waits asynchronously for a response.
  5696. Assume that both nodes are using a known socket number (in this case, 30) to receive
  5697. packets. Normally, you would want to use NBP to look up your destination’s socket
  5698. address.
  5699.  
  5700. VAR
  5701.   myABRecord: ABRecHandle;
  5702.   myBuffer: PACKED ARRAY [0..599] OF CHAR; {buffer for both send and receive}
  5703.   mySocket: Byte;
  5704.   errCode, index, dataLen: INTEGER;
  5705.   someText: Str255;
  5706.   async, retCksumErrs, doChecksum: BOOLEAN;
  5707.  
  5708. BEGIN
  5709.   errCode := MPPOpen;
  5710.   IF errCode <> noErr THEN
  5711.     WRITELN('Error in opening AppleTalk')
  5712.     {Maybe serial port B isn't available for use by AppleTalk}
  5713.   ELSE
  5714.     BEGIN
  5715.       {Call Memory Manager to allocate ABusRecord}
  5716.       myABRecord := ABRecHandle(NewHandle(ddpSize));
  5717.       mySocket := 30;
  5718.   {Add mySocket to socket table and install default socket listener to service }
  5719. { datagrams addressed to that socket. No packets addressed to mySocket will be }
  5720.       { received until we call DDPRead. }
  5721.       errCode := DDPOpenSocket(mySocket, NIL);
  5722.       IF errCode <> noErr THEN
  5723.         WRITELN('Error while opening the socket')
  5724.       {Have we opened too many socket listeners? Remember that DDP uses two of }
  5725.         { them.}
  5726.       ELSE
  5727.         BEGIN
  5728.           {Prepare data to be sent}
  5729.           someText := 'This is a sample datagram';
  5730.           dataLen := LENGTH(someText);
  5731.           FOR index := 0 TO dataLen - 1 DO {stuff buffer with packet data}
  5732.             myBuffer[index] := someText[index + 1];
  5733.           async := FALSE;
  5734.           WITH myABRecord^^ DO {fill the parameters in the ABusRecord}
  5735.             BEGIN
  5736.               ddpType := 5;
  5737.               ddpAddress.aNet := 0; {send on “our” network}
  5738.               ddpAddress.aNode := 34;
  5739.               ddpAddress.aSocket := mySocket;
  5740.               ddpReqCount := dataLen;
  5741.               ddpDataPtr := @myBuffer;
  5742.             END;
  5743.           doChecksum := FALSE;
  5744.     {If packet contains a DDP long header, compute checksum and insert it into }
  5745.           { the header.}
  5746.           errCode := DDPWrite(myABRecord, doChecksum, async); {send packet}
  5747.      {In the case of a sync call, errCode and the abResult field of myABRecord }
  5748.    { will contain the same result code. We can also reuse myABRecord, since we }
  5749.           { know whether the call has completed.}
  5750.           IF errCode <> noErr THEN
  5751.             WRITELN('Error while writing out the packet')
  5752.             {Maybe the receiving node wasn't on-line}
  5753.           ELSE
  5754.             BEGIN
  5755.            {We have sent out the packet and are now waiting for a response. We }
  5756.            { issue an async DDPRead call so that we don't “hang” waiting for a }
  5757.           { response that may not come. To cancel the async read call, we must }
  5758.               { close the socket associated with the call or call DDPRdCancel.}
  5759.               async := TRUE;
  5760.               retCksumErrs := TRUE; {return packets even if }
  5761.                                     { they have a checksum error}
  5762.               WITH myABRecord^^ DO
  5763.                 BEGIN
  5764.                   ddpSocket := mySocket;
  5765.                   ddpReqCount := 600; {our reception buffer is max size}
  5766.                   ddpDataPtr := @myBuffer;
  5767.                 END;
  5768.               {Wait for a packet asynchronously}
  5769.               errCode := DDPRead(myABRecord, retCksumErrs, async);
  5770.               IF errCode <> noErr THEN
  5771.                 WRITELN('Error while trying to queue up a DDPRead')
  5772.                 {Was the socket listener installed correctly?}
  5773.               ELSE
  5774.                 BEGIN
  5775.                   {We can either sit here in a loop and poll the }
  5776.                   { abResult field or just exit our code and use the }
  5777.                   { event mechanism to flag us when the packet arrives.}
  5778.                   CheckForMyEvent; {your procedure for checking for a }
  5779.                                    { network event}
  5780.                   {If there were no errors, a packet is inside the array }
  5781.                   { mybuffer, the length is in ddpActCount, and the }
  5782.                   { address of the sending socket is in ddpAddress. }
  5783.                   { Process the packet received here and report any errors.}
  5784.                   errCode := DDPCloseSocket(mySocket); {we're done with it}
  5785.                   IF errCode <> noErr THEN
  5786.                     WRITELN('Error while closing the socket');
  5787.                 END;
  5788.             END;
  5789.         END;
  5790.     END;
  5791. END.
  5792.  
  5793. æKY ATPLoad
  5794. æFc AppleTalk.h
  5795. æT Function
  5796. æD pascal OSErr ATPLoad(void); 
  5797. æDT OSErr myVariable = ATPLoad()(void);
  5798. æMM
  5799. æRT 20, 224
  5800. æRI II-290, N20-2
  5801. æC 
  5802. •••Refer to Technical Note #224:•••
  5803.  
  5804. ATPLoad first verifies that the .MPP driver is loaded and running. If it isn’t,
  5805. ATPLoad verifies that port B is configured for AppleTalk and isn’t in use, and then
  5806. loads MPP into the system heap.
  5807.  
  5808. ATPLoad then loads the .ATP driver, unless it’s already in memory. On a Macintosh
  5809. 128K, ATPLoad reads the .ATP driver from the system resource file into the application
  5810. heap; on a Macintosh 512K or XL, ATP is read into the system heap.
  5811.  
  5812. Note:  On a Macintosh 512K or XL, ATPLoad and MPPOpen perform essentially
  5813.        the same function.
  5814.  
  5815. Result codes    noErr        No error
  5816.                 portInUse    Port B is already in use
  5817.                 portNotCf    Port B not configured for AppleTalk
  5818.  
  5819. æKY ATPUnload
  5820. æFc AppleTalk.h
  5821. æT Function
  5822. æD pascal OSErr ATPUnload(void); 
  5823. æDT OSErr myVariable = ATPUnload()(void);
  5824. æRI II-290
  5825. æC 
  5826. ATPUnload makes the .ATP driver purgeable; the space isn’t actually released by the
  5827. Memory Manager until necessary.
  5828.  
  5829. Note:  This call applies only to a Macintosh 128K; on a Macintosh 512K
  5830.        or Macintosh XL, ATPUnload has no effect.
  5831.  
  5832. Result codes    noErr    No error
  5833.  
  5834. æKY ATPOpenSocket
  5835. æFc AppleTalk.h
  5836. æT Function
  5837. æD pascal OSErr ATPOpenSocket(const AddrBlock *addrRcvd,short *atpSocket); 
  5838. æDT OSErr myVariable = ATPOpenSocket((const AddrBlock *) addrRcvd,(short *) atpSocket);
  5839. æMM
  5840. æRI II-290
  5841. æC 
  5842. ATPOpenSocket opens a socket for the purpose of receiving requests. ATPSocket contains
  5843. the socket number of the socket to open; if it’s 0, a number is dynamically assigned
  5844. and returned in atpSocket. AddrRcvd contains a filter of the sockets from which
  5845. requests will be accepted. A 0 in the network number, node ID, or socket number field
  5846. of the addrRcvd record acts as a “wild card”; for instance, a 0 in the socket number
  5847. field means that requests will be accepted from all sockets in the node(s) specified
  5848. by the network and node fields.
  5849.  
  5850. Result codes    noErr          No error
  5851.                 tooManySkts    Socket table full
  5852.                 noDataArea     Too many outstanding ATP calls
  5853.  
  5854. Note:  If you’re only going to send requests and receive responses to
  5855.        these requests, you don’t need to open an ATP socket. When you
  5856.        make the ATPSndRequest or ATPRequest call, ATP automatically
  5857.        opens a dynamically assigned socket for that purpose.
  5858.  
  5859. æKY ATPCloseSocket
  5860. æFc AppleTalk.h
  5861. æT Function
  5862. æD pascal OSErr ATPCloseSocket(short atpSocket); 
  5863. æDT OSErr myVariable = ATPCloseSocket((short) atpSocket);
  5864. æMM
  5865. æRI II-291
  5866. æC 
  5867. ATPCloseSocket closes the responding socket whose number is specified by atpSocket.
  5868. It releases the data structures associated with all pending, asynchronous calls
  5869. involving that socket; these pending calls are completed immediately and return the
  5870. result code sktClosed.
  5871.  
  5872. Result codes    noErr         No error
  5873.                 noDataArea    Too many outstanding ATP calls
  5874.  
  5875. æKY ATPSndRequest
  5876. æFc AppleTalk.h
  5877. æT Function
  5878. æD pascal OSErr ATPSndRequest(ATATPRecHandle abRecord,Boolean async); 
  5879. æDT OSErr myVariable = ATPSndRequest((ATATPRecHandle) abRecord,(Boolean) async);
  5880. æMM
  5881. æRI II-291
  5882. æC 
  5883. ABusRecord
  5884.   <--    abOpcode         {always tATPSndRequest}
  5885.   <--    abResult         {result code}
  5886.   -->    abUserReference  {for your use}
  5887.   -->    atpAddress       {destination socket address}
  5888.   -->    atpReqCount      {request size in bytes}
  5889.   -->    atpDataPtr       {pointer to buffer}
  5890.   -->    atpRspBDSPtr     {pointer to response BDS}
  5891.   -->    atpUserData      {user bytes}
  5892.   -->    atpXO            {exactly-once flag}
  5893.   <--    atpEOM           {end-of-message flag}
  5894.   -->    atpTimeOut       {retry timeout interval in seconds}
  5895.   -->    atpRetries       {maximum number of retries}
  5896.   -->    atpNumBufs       {number of elements in response BDS}
  5897.   <--    atpNumRsp        {number of response packets actually received}
  5898.  
  5899. ATPSndRequest sends a request to another socket. ATPAddress is the internet address
  5900. of the socket to which the request should be sent. ATPDataPtr and atpReqCount specify
  5901. the location and size of a buffer that contains the request information to be sent.
  5902. ATPUserData contains the user bytes for the ATP header.
  5903.  
  5904. ATPSndRequest requires you to allocate a response BDS. ATPRspBDSPtr is a pointer to
  5905. the response BDS; atpNumBufs indicates the number of elements in the BDS (this is
  5906. also the maximum number of response datagrams that will be accepted). The number of
  5907. response datagrams actually received is returned in atpNumRsp; if a nonzero value is
  5908. returned, you can examine the response BDS to determine which packets of the transaction
  5909. were actually received. If the number returned is less than requested, one of the
  5910. following is true:
  5911.  
  5912.   •  Some of the packets have been lost and the retry count has been exceeded.
  5913.   •  ATPEOM is TRUE; this means that the response consisted of fewer packets
  5914.      than were expected, but that all packets sent were received (the last
  5915.      packet came with the atpEOM flag set).
  5916.  
  5917. ATPTimeOut indicates the length of time that ATPSndRequest should wait for a response
  5918. before retransmitting the request. ATPRetries indicates the maximum number of retries
  5919. ATPSndRequest should attempt. ATPXO should be TRUE if you want the request to be part
  5920. of an exactly-once transaction.
  5921.  
  5922. ATPSndRequest completes when either the transaction is completed or the retry count
  5923. is exceeded.
  5924.  
  5925. Result codes    noErr          No error
  5926.                 reqFailed      Retry count exceeded
  5927.                 tooManyReqs    Too many concurrent requests
  5928.                 noDataArea     Too many outstanding ATP calls
  5929.  
  5930. æKY ATPRequest
  5931. æFc AppleTalk.h
  5932. æT Function
  5933. æD pascal OSErr ATPRequest(ATATPRecHandle abRecord,Boolean async); 
  5934. æDT OSErr myVariable = ATPRequest((ATATPRecHandle) abRecord,(Boolean) async);
  5935. æMM
  5936. æRI II-292
  5937. æC 
  5938. ABusRecord
  5939.   <--    abOpcode         {always tATPRequest}
  5940.   <--    abResult         {result code}
  5941.   -->    abUserReference  {for your use}
  5942.   -->    atpAddress       {destination socket address}
  5943.   -->    atpReqCount      {request size in bytes}
  5944.   -->    atpDataPtr       {pointer to buffer}
  5945.   <--    atpActCount      {number of bytes actually received}
  5946.   -->    atpUserData      {user bytes}
  5947.   -->    atpXO            {exactly-once flag}
  5948.   <--    atpEOM           {end-of-message flag}
  5949.   -->    atpTimeOut       {retry timeout interval in seconds}
  5950.   -->    atpRetries       {maximum number of retries}
  5951.   <--    atpRspUData      {user bytes received in transaction response}
  5952.   -->    atpRspBuf        {pointer to response message buffer}
  5953.   -->    atpRspSize       {size of response message buffer}
  5954.  
  5955. ATPRequest is functionally analogous to ATPSndRequest. It sends a request to another
  5956. socket, but doesn’t require the caller to set up and use the BDS data structure to
  5957. describe the response buffers. ATPAddress indicates the socket to which the request
  5958. should be sent. ATPDataPtr and atpReqCount specify the location and size of a buffer
  5959. that contains the request information to be sent. ATPUserData contains the user bytes
  5960. to be sent in the request’s ATP header. ATPTimeOut indicates the length of time that
  5961. ATPRequest should wait for a response before retransmitting the request. ATPRetries
  5962. indicates the maximum number of retries ATPRequest should attempt.
  5963.  
  5964. To use this call, you must have an area of contiguous buffer space that’s large
  5965. enough to receive all expected datagrams. The various datagrams will be assembled in
  5966. this buffer and returned to you as a complete message upon completion of the transaction.
  5967. The location and size of this buffer are passed in atpRspBuf and atpRspSize. Upon
  5968. completion of the call, the size of the received response message is returned in
  5969. atpActCount. The user bytes received in the ATP header of the first response packet
  5970. are returned in atpRspUData. ATPXO should be TRUE if you want the request to be part
  5971. of an exactly-once transaction.
  5972.  
  5973. Although you don’t provide a BDS, ATPRequest in fact creates one and calls the
  5974. .ATP driver (as in an ATPSndRequest call). For this reason, the abRecord fields
  5975. atpRspBDSPtr and atpNumBufs are used by ATPRequest; you should not expect these
  5976. fields to remain unaltered during or after the function’s execution.
  5977.  
  5978. For ATPRequest to receive and correctly deliver the response as a single message, the
  5979. responding end must, upon receiving the request (with an ATPGetRequest call), generate
  5980. the complete response as a message in a single buffer and then call ATPResponse.
  5981.  
  5982. Note:  The responding end could also use ATPSndRsp and ATPAddRsp provided
  5983.        that each response packet (except the last one) contains exactly 578
  5984.        ATP data bytes; the last packet in the response can contain less than
  5985.        578 ATP data bytes. Also, if this method is used, only the ATP user
  5986.        bytes of the first response packet will be delivered to the requester;
  5987.        any information in the user bytes of the remaining response packets
  5988.        will not be delivered.
  5989.  
  5990. ATPRequest completes when either the transaction is completed or the retry count is
  5991. exceeded.
  5992.  
  5993. Result codes    noErr          No error
  5994.                 reqFailed      Retry count exceeded
  5995.                 tooManyReqs    Too many concurrent requests
  5996.                 sktClosed      Socket closed by a cancel call
  5997.                 noDataArea     Too many outstanding ATP calls
  5998.  
  5999. æKY ATPReqCancel
  6000. æFc AppleTalk.h
  6001. æT Function
  6002. æD pascal OSErr ATPReqCancel(ATATPRecHandle abRecord,Boolean async); 
  6003. æDT OSErr myVariable = ATPReqCancel((ATATPRecHandle) abRecord,(Boolean) async);
  6004. æMM
  6005. æRI II-293
  6006. æC 
  6007. Given the handle to the ABusRecord of a previously made ATPSndRequest or ATPRequest
  6008. call, ATPReqCancel dequeues the ATPSndRequest or ATPRequest call, provided that the
  6009. call hasn’t already completed. ATPReqCancel returns noErr if the ATPSndRequest or
  6010. ATPRequest call is successfully removed from the queue. If it returns cbNotFound,
  6011. check the abResult field of abRecord to verify that the ATPSndRequest or ATPRequest
  6012. call has completed and determine its outcome.
  6013.  
  6014. Result codes    noErr         No error
  6015.                 cbNotFound    ATP control block not found
  6016.  
  6017. æKY ATPGetRequest
  6018. æFc AppleTalk.h
  6019. æT Function
  6020. æD pascal OSErr ATPGetRequest(ATATPRecHandle abRecord,Boolean async); 
  6021. æDT OSErr myVariable = ATPGetRequest((ATATPRecHandle) abRecord,(Boolean) async);
  6022. æMM
  6023. æRT 20
  6024. æRI II-293, N20-2
  6025. æC  
  6026. ABusRecord
  6027.   <--    abOpcode         {always tATPGetRequest}
  6028.   <--    abResult         {result code}
  6029.   -->    abUserReference  {for your use}
  6030.   -->    atpSocket        {listening socket number}
  6031.   <--    atpAddress       {source socket address}
  6032.   -->    atpReqCount      {buffer size in bytes}
  6033.   -->    atpDataPtr       {pointer to buffer}
  6034.   <--    atpBitMap        {transaction bit map}
  6035.   <--    atpTransID       {transaction ID}
  6036.   <--    atpActCount      {number of bytes actually received}
  6037.   <--    atpUserData      {user bytes}
  6038.   <--    atpXO            {exactly-once flag}
  6039.  
  6040. ATPGetRequest sets up the mechanism to receive a request sent by either an ATPSndRequest
  6041. or an ATPRequest call. ATPSocket contains the socket number of the socket that should
  6042. listen for a request; this socket must already have been opened by calling ATPOpenSocket.
  6043. The address of the socket from which the request was sent is returned in atpAddress.
  6044. ATPDataPtr specifies a buffer to store the incoming request; atpReqCount indicates
  6045. the size of the buffer in bytes. The number of bytes actually received in the request
  6046. is returned in atpActCount. ATPUserData contains the user bytes from the ATP header.
  6047. The transaction bit map is returned in atpBitMap. The transaction ID is returned in
  6048. atpTransID. ATPXO will be TRUE if the request is part of an exactly-once transaction.
  6049.  
  6050. ATPGetRequest completes when a request is received. To cancel an asynchronous ATPGetRequest
  6051. call, you must call ATPCloseSocket, but this cancels all pending calls involving that
  6052. socket.
  6053.  
  6054. Result codes    noErr        No error
  6055.                 badATPSkt    Bad responding socket
  6056.                 sktClosed    Socket closed by a cancel call
  6057.  
  6058. æKY ATPSndRsp
  6059. æFc AppleTalk.h
  6060. æT Function
  6061. æD pascal OSErr ATPSndRsp(ATATPRecHandle abRecord,Boolean async); 
  6062. æDT OSErr myVariable = ATPSndRsp((ATATPRecHandle) abRecord,(Boolean) async);
  6063. æMM
  6064. æRI II-294
  6065. æC  
  6066. ABusRecord
  6067.   <--    abOpcode         {always tATPSdRsp}
  6068.   <--    abResult         {result code}
  6069.   -->    abUserReference  {for your use}
  6070.   -->    atpSocket        {responding socket number}
  6071.   -->    atpAddress       {destination socket address}
  6072.   -->    atpRspBDSPtr     {pointer to response BDS}
  6073.   -->    atpTransID       {transaction ID}
  6074.   -->    atpEOM           {end-of-message flag}
  6075.   -->    atpNumBufs       {number of response packets being sent}
  6076.   -->    atpBDSSize       {number of elements in response BDS}
  6077.  
  6078. ATPSndRsp sends a response to another socket. ATPSocket contains the socket number
  6079. from which the response should be sent and atpAddress contains the internet address
  6080. of the socket to which the response should be sent. ATPTransID must contain the
  6081. transaction ID. ATPEOM is TRUE if the response BDS contains the final packet in a
  6082. transaction composed of a group of packets and the number of packets in the response
  6083. is less than expected. ATPRspBDSPtr points to the buffer data structure containing
  6084. the responses to be sent. ATPBDSSize indicates the number of elements in the response
  6085. BDS, and must be in the range 1 to 8. ATPNumBufs indicates the number of response
  6086. packets being sent with this call, and must be in the range 0 to 8.
  6087.  
  6088. Note:  In some situations, you may want to send only part (or possibly none)
  6089.        of your response message back immediately. For instance, you might be
  6090.        requested to send back seven disk blocks, but have only enough internal
  6091.        memory to store one block. In this case, set atpBDSSize to 7 (total
  6092.        number of response packets), atpNumBufs to 0 (number of response
  6093.        packets currently being sent), and call ATPSndRsp. Then as you read
  6094.        in one block at a time, call ATPAddRsp until all seven response
  6095.        datagrams have been sent.
  6096.  
  6097. During exactly-once transactions, ATPSndRsp won’t complete until the release packet
  6098. is received or the release timer expires.
  6099.  
  6100. Result codes    noErr         No error
  6101.                 badATPSkt     Bad responding socket
  6102.                 noRelErr      No release received
  6103.                 sktClosed     Socket closed by a cancel call
  6104.                 noDataArea    Too many outstanding ATP calls
  6105.                 badBuffNum    Bad sequence number
  6106.  
  6107. æKY ATPAddRsp
  6108. æFc AppleTalk.h
  6109. æT Function
  6110. æD pascal OSErr ATPAddRsp(ATATPRecHandle abRecord); 
  6111. æDT OSErr myVariable = ATPAddRsp((ATATPRecHandle) abRecord);
  6112. æMM
  6113. æRI II-295
  6114. æC  
  6115. ABusRecord
  6116.   <--    abOpcode         {always tATPAddRsp}
  6117.   <--    abResult         {result code}
  6118.   -->    abUserReference  {for your use}
  6119.   -->    atpSocket        {responding socket number}
  6120.   -->    atpAddress       {destination socket address}
  6121.   -->    atpReqCount      {buffer size in bytes}
  6122.   -->    atpDataPtr       {pointer to buffer}
  6123.   -->    atpTransID       {transaction ID}
  6124.   -->    atpUserData      {user bytes}
  6125.   -->    atpEOM           {end-of-message flag}
  6126.   -->    atpNumRsp        {sequence number}
  6127.  
  6128. ATPAddRsp sends one additional response packet to a socket that has already been sent
  6129. the initial part of a response via ATPSndRsp. ATPSocket contains the socket number
  6130. from which the response should be sent and atpAddress contains the internet address
  6131. of the socket to which the response should be sent. ATPTransID must contain the
  6132. transaction ID. ATPDataPtr and atpReqCount specify the location and size of a buffer
  6133. that contains the information to send; atpNumRsp is the sequence number of the response.
  6134. ATPEOM is TRUE if this response datagram is the final packet in a transaction composed
  6135. of a group of packets. ATPUserData contains the user bytes to be sent in this response
  6136. datagram’s ATP header.
  6137.  
  6138. Note:  No BDS is needed with ATPAddRsp because all pertinent information
  6139.        is passed within the record.
  6140.  
  6141. Result codes    noErr         No error
  6142.                 badATPSkt     Bad responding socket
  6143.                 badBuffNum    Bad sequence number
  6144.                 noSendResp    ATPAddRsp issued before ATPSndRsp
  6145.                 noDataArea    Too many outstanding ATP calls
  6146.  
  6147. æKY ATPResponse
  6148. æFc AppleTalk.h
  6149. æT Function
  6150. æD pascal OSErr ATPResponse(ATATPRecHandle abRecord,Boolean async); 
  6151. æDT OSErr myVariable = ATPResponse((ATATPRecHandle) abRecord,(Boolean) async);
  6152. æMM
  6153. æRT 20
  6154. æRI II-296, N20-2
  6155. æC 
  6156. ABusRecord
  6157.   <--    abOpcode         {always tATPResponse}
  6158.   <--    abResult         {result code}
  6159.   -->    abUserReference  {for your use}
  6160.   -->    atpSocket        {responding socket number}
  6161.   -->    atpAddress       {destination socket address}
  6162.   -->    atpTransID       {transaction ID)
  6163.   -->    atpRspUData      {user bytes sent in transaction response}
  6164.   -->    atpRspBuf        {pointer to response message buffer}
  6165.   -->    atpRspSize       {size of response message buffer}
  6166.  
  6167. ATPResponse is functionally analogous to ATPSndRsp. It sends a response to another
  6168. socket, but doesn’t require the caller to provide a BDS. ATPAddress must contain the
  6169. complete network address of the socket to which the response should be sent (taken
  6170. from the data provided by an ATPGetRequest call). ATPTransID must contain the transaction
  6171. ID. ATPSocket indicates the socket from which the response should be sent (the socket
  6172. on which the corresponding ATPGetRequest was issued). ATPRspBuf points to the buffer
  6173. containing the response message; the size of this buffer must be passed in atpRspSize.
  6174. The four user bytes to be sent in the ATP header of the first response packet are
  6175. passed in atpRspUData. The last packet of the transaction response is sent with the
  6176. EOM flag set.
  6177.  
  6178. Although you don’t provide a BDS, ATPResponse in fact creates one and calls the .ATP
  6179. driver (as in an ATPSndRsp call). For this reason, the abRecord fields atpRspBDSPtr
  6180. and atpNumBufs are used by ATPResponse; you should not expect these fields to remain
  6181. unaltered during or after the function’s execution.
  6182.  
  6183. During exactly-once transactions ATPResponse won’t complete until the release packet
  6184. is received or the release timer expires.
  6185.  
  6186. Warning:  The maximum permissible size of the response message is 4624 bytes.
  6187.  
  6188. Result codes    noErr         No error
  6189.                 badATPSkt     Bad responding socket
  6190.                 noRelErr      No release received
  6191.                 atpLenErr     Response too big
  6192.                 sktClosed     Socket closed by a cancel call
  6193.                 noDataArea    Too many outstanding ATP calls
  6194.  
  6195. æKY ATPRspCancel
  6196. æFc AppleTalk.h
  6197. æT Function
  6198. æD pascal OSErr ATPRspCancel(ATATPRecHandle abRecord,Boolean async); 
  6199. æDT OSErr myVariable = ATPRspCancel((ATATPRecHandle) abRecord,(Boolean) async);
  6200. æMM
  6201. æRI II-296
  6202. æC 
  6203. Given the handle to the ABusRecord of a previously made ATPSndRsp or ATPResponse
  6204. call, ATPRspCancel dequeues the ATPSndRsp or ATPResponse call, provided that the call
  6205. hasn’t already completed. ATPRspCancel returns noErr if the ATPSndRsp or ATPResponse
  6206. call is successfully removed from the queue. If it returns cbNotFound, check the
  6207. abResult field of abRecord to verify that the ATPSndRsp or ATPResponse call has
  6208. completed and determine its outcome.
  6209.  
  6210. Result codes    noErr         No error
  6211.                 cbNotFound    ATP control block not found
  6212.  
  6213. »Example
  6214.  
  6215. This example shows the requesting side of an ATP transaction that asks for a 512-byte
  6216. disk block from the responding end. The block number of the file is a byte and is
  6217. contained in myBuffer[0].
  6218.  
  6219. VAR
  6220.   myABRecord: ABRecHandle;
  6221.   myBDSPtr: BDSPtr;
  6222.   myBuffer: PACKED ARRAY [0..511] OF CHAR;
  6223.   errCode: INTEGER;
  6224.   async: BOOLEAN;
  6225.  
  6226. BEGIN
  6227.   errCode := ATPLoad;
  6228.   IF errCode <> noErr THEN
  6229.     WRITELN('Error in opening AppleTalk')
  6230.     {Maybe serial port B isn't available for use by AppleTalk}
  6231.   ELSE
  6232.     BEGIN
  6233.       {Prepare the BDS; allocate space for a one-element BDS}
  6234.       myBDSPtr := BDSPtr(NewPtr(SIZEOF(BDSElement)));
  6235.       WITH myBDSPtr^[0] DO
  6236.         BEGIN
  6237.           buffSize := 512; {size of our buffer used in reception}
  6238.           buffPtr := @myBuffer; {pointer to the buffer}
  6239.         END;
  6240.       {Prepare the ABusRecord}
  6241.       myBuffer[0] := CHR(1); {requesting disk block number 1}
  6242.       myABRecord := ABRecHandle(NewHandle(atpSize));
  6243.       WITH myABRecord^^ DO
  6244.         BEGIN
  6245.           atpAddress.aNet := 0;
  6246.           atpAddress.aNode := 30; {we probably got this from an NBP call}
  6247.           atpAddress.aSocket := 15; {socket to send request to}
  6248.           atpReqCount := 1; {size of request data field (disk block #)}
  6249.           atpDataPtr := @myBuffer; {ptr to request to be sent}
  6250.           atpRspBDSPtr := @myBDSPtr;
  6251.           atpUserData := 0; {for your use}
  6252.           atpXO := FALSE; {at-least-once service}
  6253.           atpTimeOut := 5; {5-second timeout}
  6254.           atpRetries := 3; {3 retries; request will be sent 4 times max}
  6255.           atpNumBufs := 1; {we're only expecting 1 block to be returned}
  6256.         END;
  6257.       async := FALSE;
  6258.       {Send the request and wait for the response}
  6259.       errCode := ATPSndRequest(myABRecord, async);
  6260.       IF errCode <> noErr THEN
  6261.         WRITELN('An error occurred in the ATPSndRequest call')
  6262.       ELSE
  6263.         BEGIN
  6264.           {The disk block requested is now in myBuffer. We can verify }
  6265.           { that atpNumRsp contains 1, meaning one response received.}
  6266.         . . .
  6267.         END;
  6268.     END;
  6269. END.
  6270.  
  6271. æKY NBPRegister
  6272. æFc AppleTalk.h
  6273. æT Function
  6274. æD pascal OSErr NBPRegister(ATNBPRecHandle abRecord,Boolean async); 
  6275. æDT OSErr myVariable = NBPRegister((ATNBPRecHandle) abRecord,(Boolean) async);
  6276. æMM
  6277. æRT 20
  6278. æRI II-299, N20-2
  6279. æC 
  6280. ABusRecord
  6281.   <--    abOpcode            {always tNBPRegister}
  6282.   <--    abResult            {result code}
  6283.   -->    abUserReference     {for your use}
  6284.   -->    nbpEntityPtr        {pointer to entity name}
  6285.   -->    nbpBufPtr           {pointer to buffer}
  6286.   -->    nbpBufSize          {buffer size in bytes}
  6287.   -->    nbpAddress.aSocket  {socket address}
  6288.   -->    nbpRetransmitInfo   {retransmission information}
  6289.  
  6290. NBPRegister adds the name and address of an entity to the node’s names table. NBPEntityPtr
  6291. points to a variable of type EntityName containing the entity’s name. If the name is
  6292. already registered, NBPRegister returns the result code nbpDuplicate. NBPAddress
  6293. indicates the socket for which the name should be registered. NBPBufPtr and nbpBufSize
  6294. specify the location and size of a buffer for NBP to use internally.
  6295.  
  6296. While the variable of type EntityName is declared as three 32-byte strings, only the
  6297. actual characters of the name are placed in the buffer pointed to by nbpBufPtr. For
  6298. this reason, nbpBufSize needs only to be equal to the actual length of the name, plus
  6299. an additional 12 bytes for use by NBP.
  6300.  
  6301. Warning:  This buffer must not be altered or released until the name is
  6302.           removed from the names table via an NBPRemove call. If you
  6303.           allocate the buffer through a NewHandle call, you must lock
  6304.           it as long as the name is registered.
  6305.  
  6306. Warning:  The zone field of the entity name must be set to the
  6307.           meta-character “*”.
  6308.  
  6309. Result codes    noErr           No error
  6310.                 nbpDuplicate    Duplicate name already exists
  6311.  
  6312. æKY NBPLookup
  6313. æFc AppleTalk.h
  6314. æT Function
  6315. æD pascal OSErr NBPLookup(ATNBPRecHandle abRecord,Boolean async); 
  6316. æDT OSErr myVariable = NBPLookup((ATNBPRecHandle) abRecord,(Boolean) async);
  6317. æMM
  6318. æRT 9, 20
  6319. æRI II-300, N9-1, 2, N20-2 
  6320. æC 
  6321. ABusRecord
  6322.   <--    abOpcode           {always tNBPLookup}
  6323.   <--    abResult           {result code}
  6324.   -->    abUserReference    {for your use}
  6325.   -->    nbpEntityPtr       {pointer to entity name}
  6326.   -->    nbpBufPtr          {pointer to buffer}
  6327.   -->    nbpBufSize         {buffer size in bytes}
  6328.   <->    nbpDataField       {number of addresses received}
  6329.   -->    nbpRetransmitInfo  {retransmission information}
  6330.  
  6331. NBPLookup returns the addresses of all entities with a specified name. NBPEntityPtr
  6332. points to a variable of type EntityName containing the name of the entity whose
  6333. address should be returned. (Meta-characters are allowed in the entity name.) NBPBufPtr
  6334. and nbpBufSize contain the location and size of an area of memory in which the entity
  6335. names and their corresponding addresses should be returned. NBPDataField indicates
  6336. the maximum number of matching names to find addresses for; the actual number of
  6337. addresses found is returned in nbpDataField. NBPRetransmitInfo contains the retry
  6338. interval and the retry count.
  6339.  
  6340. When specifying nbpBufSize, for each NBP tuple expected, allow space for the actual
  6341. characters of the name, the address, and four bytes for use by NBP.
  6342.  
  6343. Result codes    noErr         No error
  6344.                 nbpBuffOvr    Buffer overflow
  6345.  
  6346. æKY NBPExtract
  6347. æFc AppleTalk.h
  6348. æT Function
  6349. æD pascal OSErr NBPExtract(Ptr theBuffer,short numInBuf,short whichOne,EntityName *abEntity,
  6350.     AddrBlock *address); 
  6351. æDT OSErr myVariable = NBPExtract((Ptr) theBuffer,(short) numInBuf,(short) whichOne,(EntityName *) abEntity,(
  6352.     AddrBlock) * address);
  6353. æMM
  6354. æRI II-300,V-515
  6355. æC 
  6356. This routine is provided in the alternate interface, but can be used as provided for
  6357. extracting NBP entity names from a look-up response buffer.
  6358.  
  6359. NBPExtract returns one address from the list of addresses returned by NBPLookup.
  6360. TheBuffer and numInBuf indicate the location and number of tuples in the buffer.
  6361. WhichOne specifies which one of the tuples in the buffer should be returned in the
  6362. abEntity and address parameters.
  6363.  
  6364. Result codes    noErr         No error
  6365.                 extractErr    Can’t find tuple in buffer
  6366.  
  6367. æKY NBPConfirm
  6368. æFc AppleTalk.h
  6369. æT Function
  6370. æD pascal OSErr NBPConfirm(ATNBPRecHandle abRecord,Boolean async); 
  6371. æDT OSErr myVariable = NBPConfirm((ATNBPRecHandle) abRecord,(Boolean) async);
  6372. æMM
  6373. æRT 9
  6374. æRI II-301, N9-2
  6375. æC 
  6376. ABusRecord
  6377.   <--    abOpcode           {always tNBPConfirm}
  6378.   <--    abResult           {result code}
  6379.   -->    abUserReference    {for your use}
  6380.   -->    nbpEntityPtr       {pointer to entity name}
  6381.   <--    nbpDataField       {socket number}
  6382.   -->    nbpAddress         {socket address}
  6383.   -->    nbpRetransmitInfo  {retransmission information}
  6384.  
  6385. NBPConfirm confirms that an entity known by name and address still exists (is still
  6386. entered in the names directory). NBPEntityPtr points to a variable of type EntityName
  6387. that contains the name to confirm, and nbpAddress specifies the address to be confirmed.
  6388. (No meta-characters are allowed in the entity name.) NBPRetransmitInfo contains the
  6389. retry interval and the retry count. The socket number of the entity is returned in
  6390. nbpDataField. NBPConfirm is more efficient than NBPLookup in terms of network traffic.
  6391.  
  6392. Result codes    noErr           No error
  6393.                 nbpConfDiff     Name confirmed for different socket
  6394.                 nbpNoConfirm    Name not confirmed
  6395.  
  6396. æKY NBPRemove
  6397. æFc AppleTalk.h
  6398. æT Function
  6399. æD pascal OSErr NBPRemove(EntityPtr abEntity); 
  6400. æDT OSErr myVariable = NBPRemove((EntityPtr) abEntity);
  6401. æMM
  6402. æRI II-301
  6403. æC 
  6404. NBPRemove removes an entity name from the names table of the given entity’s node.
  6405.  
  6406. Result codes    noErr          No error
  6407.                 nbpNotFound    Name not found
  6408.  
  6409. æKY NBPLoad
  6410. æFc AppleTalk.h
  6411. æT Function
  6412. æD pascal OSErr NBPLoad(void); 
  6413. æDT OSErr myVariable = NBPLoad()(void);
  6414. æMM
  6415. æRI II-301
  6416. æC 
  6417. On a Macintosh 128K, NBPLoad reads the NBP code from the system resource file into
  6418. the application heap. On a Macintosh 512K or XL, NBPLoad has no effect since the NBP
  6419. code should have already been loaded when the .MPP driver was opened. Normally you’ll
  6420. never need to call NBPLoad, because the AppleTalk Manager calls it when necessary.
  6421.  
  6422. Result codes    noErr    No error
  6423.  
  6424. æKY NBPUnload
  6425. æFc AppleTalk.h
  6426. æT Function
  6427. æD pascal OSErr NBPUnload(void); 
  6428. æDT OSErr myVariable = NBPUnload()(void);
  6429. æMM
  6430. æRI II-301
  6431. æC 
  6432. On a Macintosh 128K, NBPUnload makes the NBP code purgeable; the space isn’t actually
  6433. released by the Memory Manager until necessary. On a Macintosh 512K or Macintosh XL,
  6434. NBPUnload has no effect.
  6435.  
  6436. Result codes    noErr    No error
  6437.  
  6438. »Example
  6439.  
  6440. This example of NBP registers our node as a print spooler, searches for any print
  6441. spoolers registered on the network, and then extracts the information for the first
  6442. one found.
  6443.  
  6444. CONST
  6445.   mySocket = 20;
  6446.  
  6447. VAR
  6448.   myABRecord: ABRecHandle;
  6449.   myEntity: EntityName;
  6450.   entityAddr: AddrBlock;
  6451.   nbpNamePtr: Ptr;
  6452.   myBuffer: PACKED ARRAY [0..999] OF CHAR;
  6453.   errCode: INTEGER;
  6454.   async: BOOLEAN;
  6455.  
  6456. BEGIN
  6457.   errCode := MPPOpen;
  6458.   IF errCode <> noErr THEN
  6459.     WRITELN('Error in opening AppleTalk')
  6460.     {Maybe serial port B isn't available for use by AppleTalk}
  6461.   ELSE
  6462.     BEGIN
  6463.       {Call Memory Manager to allocate ABusRecord}
  6464.       myABRecord := ABRecHandle(NewHandle(nbpSize));
  6465.       {Set up our entity name to register}
  6466.       WITH myEntity DO
  6467.         BEGIN
  6468.           objStr := 'Gene Station'; {we are called 'Gene Station' }
  6469.           typeStr := 'PrintSpooler'; { and are of type 'PrintSpooler'}
  6470.           zoneStr := '*';
  6471.           {Allocate data space for the entity name (used by NBP)}
  6472.           nbpNamePtr := NewPtr(LENGTH(objStr) + LENGTH(typeStr) +
  6473.                                LENGTH(zoneStr) + 12);
  6474.         END;
  6475.       {Set up the ABusRecord for the NBPRegister call}
  6476.       WITH myABRecord^^ DO
  6477.         BEGIN
  6478.           nbpEntityPtr := @myEntity;
  6479.           nbpBufPtr := nbpNamePtr; {buffer used by NBP internally}
  6480.           nbpBufSize := nbpNameBufSize;
  6481.           nbpAddress.aSocket := mySocket; {socket to register us on}
  6482.           nbpRetransmitInfo.retransInterval := 8; {retransmit every 64 }
  6483.           nbpRetransmitInfo.retransCount := 3; { ticks and try 3 times}
  6484.         END;
  6485.       async := FALSE;
  6486.       errCode := NBPRegister(myABRecord, async);
  6487.       IF errCode <> noErr THEN
  6488.         WRITELN('Error occurred in the NBPRegister call')
  6489.         {Maybe the name is already registered somewhere else on the }
  6490.         { network.}
  6491.       ELSE
  6492.         BEGIN
  6493.           {Now that we've registered our name, find others of type }
  6494.           { 'PrintSpooler'.}
  6495.           WITH myEntity DO
  6496.             BEGIN
  6497.               objStr := '='; {any one of type }
  6498.               typeStr := 'PrintSpooler'; { “PrintSpooler” }
  6499.               zoneStr := '*'; { in our zone}
  6500.             END;
  6501.           WITH myABRecord^^ DO
  6502.             BEGIN
  6503.               nbpEntityPtr := @myEntity;
  6504.               nbpBufPtr := @myBuffer; {buffer to place responses in}
  6505.               nbpBufSize := SIZEOF(myBuffer);
  6506.              {The field nbpDataField, before the NBPLookup call, represents an }
  6507.               { approximate number of responses. After the call, nbpDataField }
  6508.               { contains the actual number of responses received.}
  6509.               nbpDataField := 100; {we want about 100 responses back}
  6510.             END;
  6511.           errCode := NBPLookup(myABRecord, async); {make sync call}
  6512.           IF errCode <> noErr THEN
  6513.             WRITELN('An error occurred in the NBPLookup')
  6514.             {Did the buffer overflow?}
  6515.           ELSE
  6516.             BEGIN
  6517.               {Get the first reply}
  6518.               errCode := NBPExtract(@mybuffer, myABRecord^^.nbpDataField, 1,
  6519.                                     myEntity, entityAddr);
  6520.            {The socket address and name of the entity are returned here. If we }
  6521.              { want all of them, we'll have to loop for each one in the buffer.}
  6522.               IF errCode <> noErr THEN WRITELN('Error in NBPExtract');
  6523.               {Maybe the one we wanted wasn't in the buffer}
  6524.             END;
  6525.         END;
  6526.     END;
  6527. END.
  6528.  
  6529. æKY RemoveHdlBlocks
  6530. æFc AppleTalk.h
  6531. æT Function
  6532. æD pascal void RemoveHdlBlocks(void); 
  6533. æDT RemoveHdlBlocks()(void);
  6534. æC 
  6535.  
  6536. æKY GetNodeAddress
  6537. æFc AppleTalk.h
  6538. æT Function
  6539. æD pascal OSErr GetNodeAddress(short *myNode,short *myNet); 
  6540. æDT OSErr myVariable = GetNodeAddress((short *) myNode,(short *) myNet);
  6541. æRI II-303
  6542. æC 
  6543. GetNodeAddress returns the current node ID and network number of the caller. If the
  6544. .MPP driver isn’t installed, it returns noMPPErr. If myNet contains 0, this means
  6545. that a bridge hasn’t yet been found.
  6546.  
  6547. Result codes    noErr       No error
  6548.                 noMPPErr    MPP driver not installed
  6549.  
  6550. æKY IsMPPOpen
  6551. æFc AppleTalk.h
  6552. æT Function
  6553. æD pascal Boolean IsMPPOpen(void); 
  6554. æDT Boolean myVariable = IsMPPOpen()(void);
  6555. æRI II-304
  6556. æC 
  6557. [Not in ROM]
  6558.  
  6559. IsMPPOpen returns TRUE if the .MPP driver is loaded and running.
  6560.  
  6561. æKY IsATPOpen
  6562. æFc AppleTalk.h
  6563. æT Function
  6564. æD pascal Boolean IsATPOpen(void); 
  6565. æDT Boolean myVariable = IsATPOpen()(void);
  6566. æRI II-304
  6567. æC 
  6568. [Not in ROM]
  6569.  
  6570. IsATPOpen returns TRUE if the .ATP driver is loaded and running.
  6571.  
  6572.  
  6573. æKY Assert.h
  6574. æC 
  6575. assert
  6576.  
  6577. #include <Assert.h>
  6578. void assert (int expression);
  6579.  
  6580.                            Description
  6581.  
  6582. The assert; macro allows your program to send diagnostic 
  6583. messages to the user, depending on the evaluation of 
  6584. expression. If expression is false, assert provides an error 
  6585. message, and then calls the abort function. The format for this 
  6586. message is FILE myfile.c; Line 108 ##assertion failed: i<j
  6587.  
  6588. The assert macro can be activated using the NDEBUG macro. If 
  6589. NDEBUG is turned off, assert will evaluate expression.
  6590.  
  6591.                            Note
  6592.  
  6593. The message pointed to by assert is an executable MPW 
  6594. command. When the command is executed, it will open the 
  6595. source file containing the assert and highlight the assert statement.
  6596.  
  6597. Example
  6598. #include <assert.h>
  6599. main()
  6600. {
  6601.  int i,j;
  6602.  i = foo();
  6603.  j = 3;
  6604.  assert (i<100);         /* This depends on the compile-time */
  6605.                          /* setting of NDEBUG. If */
  6606.                          /* NDEBUG is defined,  the assert */
  6607.                          /* statement is not passed from the  */
  6608.                          /* preprocessor to the compiler */
  6609.  #undef NDEBUG           /* Turn off NDEBUG */
  6610.  #include <assert.h>
  6611.  assert (i<j);           /* This assert is turned on */
  6612.  #define NDEBUG          /* Turn on NDEBUG */
  6613.  #include <assert.h>
  6614.  j = foo();
  6615.  assert (j <100);        /* This assert is turned off */
  6616. }
  6617. See also
  6618. abort
  6619.  
  6620. æKY assert
  6621. æFc Assert.h
  6622. æC #include <Assert.h>
  6623. void assert (int expression);
  6624.  
  6625.                            Description
  6626.  
  6627. The assert; macro allows your program to send diagnostic 
  6628. messages to the user, depending on the evaluation of 
  6629. expression. If expression is false, assert provides an error 
  6630. message, and then calls the abort function. The format for this 
  6631. message is FILE myfile.c; Line 108 ##assertion failed: i<j
  6632.  
  6633. The assert macro can be activated using the NDEBUG macro. If 
  6634. NDEBUG is turned off, assert will evaluate expression.
  6635.  
  6636.                            Note
  6637.  
  6638. The message pointed to by assert is an executable MPW 
  6639. command. When the command is executed, it will open the 
  6640. source file containing the assert and highlight the assert statement.
  6641.  
  6642. Example
  6643. #include <assert.h>
  6644. main()
  6645. {
  6646.  int i,j;
  6647.  i = foo();
  6648.  j = 3;
  6649.  assert (i<100);         /* This depends on the compile-time */
  6650.                          /* setting of NDEBUG. If */
  6651.                          /* NDEBUG is defined,  the assert */
  6652.                          /* statement is not passed from the  */
  6653.                          /* preprocessor to the compiler */
  6654.  #undef NDEBUG           /* Turn off NDEBUG */
  6655.  #include <assert.h>
  6656.  assert (i<j);           /* This assert is turned on */
  6657.  #define NDEBUG          /* Turn on NDEBUG */
  6658.  #include <assert.h>
  6659.  j = foo();
  6660.  assert (j <100);        /* This assert is turned off */
  6661. }
  6662. See also
  6663. abort
  6664.  
  6665. æKY assertæ                     
  6666. æDT 
  6667. void myVariable = assert ((int) expression);
  6668.  
  6669. æKY Balloons.h
  6670. æKL HMBalloonRect
  6671. HMBaloonPict
  6672. HMExtractHelpMsg
  6673. HMFillCitationString
  6674. HMGetBalloons
  6675. HMGetDialogResID
  6676. HMGetFont
  6677. HMGetFontSize
  6678. HMGetMenuResID
  6679. HMIsBalloon
  6680. HMMouseInApplRgn
  6681. HMRemoveBalloon
  6682. HMScanTemplateItems
  6683. HMSetBalloons
  6684. HMSetDialogResID
  6685. HMSetFont
  6686. HMSetFontSize
  6687. HMSetMenuResID
  6688. HMShowBalloon
  6689. HMShowMenuBalloon
  6690.  
  6691. hdlgLocalCoords
  6692. hdlgSaveBits
  6693. hdlgUseSubID
  6694. helpItem
  6695. hmBadSelector
  6696. hmBalloonAborted
  6697. HMCompareItem
  6698. hmCouldNotLoadPackage
  6699. HMDefaultRecord
  6700. HMDefaultRecPtr
  6701. hmGestaltBalloonsOff
  6702. hmGestaltBalloonsOn
  6703. hmGestaltHelpType
  6704. hmHelpDisabled
  6705. HMLHHandleType
  6706. hmMemFullErr
  6707. HMMessageRecord
  6708. HMMessageRecordPtr
  6709. HMNamedResourceItem
  6710. HMPicHDefaultRecord
  6711. HMPicHDefaultRecPtr
  6712. HMPicHMsgRecord
  6713. HMPicHMsgRecPtr
  6714. HMPictDefaultRecord
  6715. HMPictDefaultRecPtr
  6716. HMPictItem
  6717. HMPictMsgRecord
  6718. HMPictMsgRecPtr
  6719. hmResNotFound
  6720. hmSameAsLastBalloon
  6721. HMSkipItem
  6722. hmSkippedBalloon
  6723. HMSTHandleType
  6724. HMStringDefaultRecord
  6725. HMStringDefaultRecPtr
  6726. HMStringItem
  6727. HMStringMsgRecord
  6728. HMStringMsgRecPtr
  6729. HMStringRecord
  6730. HMStringResItem
  6731. HMStringResType
  6732. HMStrResDefaultRecord
  6733. HMStrResDefaultRecPtr
  6734. HMSTRResItem
  6735. HMStrResMsgRecord
  6736. HMStrResMsgRecPtr
  6737. HMTEHDefaultRecord
  6738. HMTEHDefaultRecPtr
  6739. HMTEHMsgRecord
  6740. HMTEHMsgRecPtr
  6741. HMTEResItem
  6742. HMTEResType
  6743. HMTEStyleType
  6744. HMTrackCntlItem
  6745. hmUnknownHelpType
  6746. HMVersionWord
  6747. hmWrongVersion
  6748. hwinUseResID
  6749. hwinUseSubID
  6750. kBalloonWDEFID
  6751. kHMAboutHelpID
  6752. kHMChecked
  6753. kHMCheckedItem
  6754. kHMDisabled
  6755. kHMDisabledItem
  6756. kHMEasy1Access
  6757. kHMEasy2Access
  6758. kHMEasy3Access
  6759. kHMEnabled
  6760. kHMEnabledItem
  6761. kHMHelpIconOff
  6762. kHMHelpIconOn
  6763. kHMHelpID
  6764. kHMHelpMenuID
  6765. kHMhrctAbsolute
  6766. kHMInDisabledScrollBar
  6767. kHMInDragIndex
  6768. kHMInGoAwayIndex
  6769. kHMInGrowIndex
  6770. kHMInScrollBar
  6771. kHMInZoomIndex
  6772. kHMMenuTitleIndex
  6773. khmmPict
  6774. khmmPictHandle
  6775. khmmString
  6776. khmmStringRes
  6777. khmmSTRRes
  6778. khmmTEHandle
  6779. khmmTERes
  6780. kHMMultiFinderIndex
  6781. kHMOther
  6782. kHMOtherItem
  6783. kHMUsingHelpIndex
  6784. kHMUsingHelpItem
  6785. kHMWhatIsIndex
  6786. kHMWhatIsItem
  6787.  
  6788. æKY HMVersionWord
  6789. æFc Balloons.h
  6790. æT #define
  6791. æD #define HMVersionWord 0x0002
  6792. æC 
  6793.  
  6794. æKY hmHelpDisabled
  6795. æFc Balloons.h
  6796. æT #define
  6797. æD 
  6798. /* Help Mgr error range: -850 to -874 */
  6799.  
  6800. #define hmHelpDisabled -850
  6801. æC 
  6802.  
  6803. æKY hmResNotFound
  6804. æFc Balloons.h
  6805. æT #define
  6806. æD #define hmResNotFound -851
  6807. æC 
  6808.  
  6809. æKY hmMemFullErr
  6810. æFc Balloons.h
  6811. æT #define
  6812. æD #define hmMemFullErr -852
  6813. æC 
  6814.  
  6815. æKY hmBalloonAborted
  6816. æFc Balloons.h
  6817. æT #define
  6818. æD #define hmBalloonAborted -853
  6819. æC 
  6820.  
  6821. æKY hmSameAsLastBalloon
  6822. æFc Balloons.h
  6823. æT #define
  6824. æD #define hmSameAsLastBalloon -854
  6825. æC 
  6826.  
  6827. æKY hmBadSelector
  6828. æFc Balloons.h
  6829. æT #define
  6830. æD #define hmBadSelector -856
  6831. æC 
  6832.  
  6833. æKY hmSkippedBalloon
  6834. æFc Balloons.h
  6835. æT #define
  6836. æD #define hmSkippedBalloon -857
  6837. æC 
  6838.  
  6839. æKY hmWrongVersion
  6840. æFc Balloons.h
  6841. æT #define
  6842. æD #define hmWrongVersion -858
  6843. æC 
  6844.  
  6845. æKY hmUnknownHelpType
  6846. æFc Balloons.h
  6847. æT #define
  6848. æD #define hmUnknownHelpType -859
  6849. æC 
  6850.  
  6851. æKY hmCouldNotLoadPackage
  6852. æFc Balloons.h
  6853. æT #define
  6854. æD #define hmCouldNotLoadPackage -860
  6855. æC 
  6856.  
  6857. æKY hmGestaltHelpType
  6858. æFc Balloons.h
  6859. æT #define
  6860. æD 
  6861. /* Gestalt */
  6862.  
  6863. #define hmGestaltHelpType 'help'
  6864. æC 
  6865.  
  6866. æKY hmGestaltBalloonsOn
  6867. æFc Balloons.h
  6868. æT #define
  6869. æD #define hmGestaltBalloonsOn 0
  6870. æC 
  6871.  
  6872. æKY hmGestaltBalloonsOff
  6873. æFc Balloons.h
  6874. æT #define
  6875. æD #define hmGestaltBalloonsOff 1
  6876. æC 
  6877.  
  6878. æKY kHMUsingHelpItem
  6879. æFc Balloons.h
  6880. æT #define
  6881. æD #define kHMUsingHelpItem 1
  6882. æC 
  6883.  
  6884. æKY kHMWhatIsItem
  6885. æFc Balloons.h
  6886. æT #define
  6887. æD #define kHMWhatIsItem 3
  6888. æC 
  6889.  
  6890. æKY kHMHelpID
  6891. æFc Balloons.h
  6892. æT #define
  6893. æD #define kHMHelpID -5696
  6894. æC 
  6895.  
  6896. æKY kHMMultiFinderIndex
  6897. æFc Balloons.h
  6898. æT #define
  6899. æD 
  6900. /*  System STR# resource indexes  */
  6901.  
  6902. #define kHMMultiFinderIndex 1
  6903. æC 
  6904.  
  6905. æKY kHMMenuTitleIndex
  6906. æFc Balloons.h
  6907. æT #define
  6908. æD #define kHMMenuTitleIndex 2
  6909. æC 
  6910.  
  6911. æKY kHMUsingHelpIndex
  6912. æFc Balloons.h
  6913. æT #define
  6914. æD #define kHMUsingHelpIndex 3
  6915. æC 
  6916.  
  6917. æKY kHMWhatIsIndex
  6918. æFc Balloons.h
  6919. æT #define
  6920. æD #define kHMWhatIsIndex 4
  6921. æC 
  6922.  
  6923. æKY kHMInDragIndex
  6924. æFc Balloons.h
  6925. æT #define
  6926. æD #define kHMInDragIndex 5
  6927. æC 
  6928.  
  6929. æKY kHMInGrowIndex
  6930. æFc Balloons.h
  6931. æT #define
  6932. æD #define kHMInGrowIndex 6
  6933. æC 
  6934.  
  6935. æKY kHMInGoAwayIndex
  6936. æFc Balloons.h
  6937. æT #define
  6938. æD #define kHMInGoAwayIndex 7
  6939. æC 
  6940.  
  6941. æKY kHMInZoomIndex
  6942. æFc Balloons.h
  6943. æT #define
  6944. æD #define kHMInZoomIndex 8
  6945. æC 
  6946.  
  6947. æKY kHMInScrollBar
  6948. æFc Balloons.h
  6949. æT #define
  6950. æD #define kHMInScrollBar 9
  6951. æC 
  6952.  
  6953. æKY kHMInDisabledScrollBar
  6954. æFc Balloons.h
  6955. æT #define
  6956. æD #define kHMInDisabledScrollBar 10
  6957. æC 
  6958.  
  6959. æKY kHMEasy1Access
  6960. æFc Balloons.h
  6961. æT #define
  6962. æD #define kHMEasy1Access 11
  6963. æC 
  6964.  
  6965. æKY kHMEasy2Access
  6966. æFc Balloons.h
  6967. æT #define
  6968. æD #define kHMEasy2Access 12
  6969. æC 
  6970.  
  6971. æKY kHMEasy3Access
  6972. æFc Balloons.h
  6973. æT #define
  6974. æD #define kHMEasy3Access 13
  6975. æC 
  6976.  
  6977. æKY kHMAboutHelpID
  6978. æFc Balloons.h
  6979. æT #define
  6980. æD 
  6981. /* misc Constants */
  6982.  
  6983. #define kHMAboutHelpID -5696
  6984. æC 
  6985.  
  6986. æKY kHMHelpMenuID
  6987. æFc Balloons.h
  6988. æT #define
  6989. æD #define kHMHelpMenuID -5696
  6990. æC 
  6991.  
  6992. æKY kHMHelpIconOn
  6993. æFc Balloons.h
  6994. æT #define
  6995. æD #define kHMHelpIconOn -5696
  6996. æC 
  6997.  
  6998. æKY kHMHelpIconOff
  6999. æFc Balloons.h
  7000. æT #define
  7001. æD #define kHMHelpIconOff -5695
  7002. æC 
  7003.  
  7004. æKY kBalloonWDEFID
  7005. æFc Balloons.h
  7006. æT #define
  7007. æD 
  7008. /* WhatIs default WDEF res ID */
  7009.  
  7010. #define kBalloonWDEFID 126
  7011. æC 
  7012.  
  7013. æKY helpItem
  7014. æFc Balloons.h
  7015. æT #define
  7016. æD 
  7017. /* Dialog item template type */
  7018.  
  7019. #define helpItem 1
  7020. æC 
  7021.  
  7022. æKY kHMhrctAbsolute
  7023. æFc Balloons.h
  7024. æT #define
  7025. æD 
  7026. /* hrct Options */
  7027.  
  7028. #define kHMhrctAbsolute 0
  7029. æC 
  7030.  
  7031. æKY kHMEnabledItem
  7032. æFc Balloons.h
  7033. æT #define
  7034. æD 
  7035. /* Generic defines for the switch items used in 'hmnu' & 'hdlg' */
  7036.  
  7037. #define kHMEnabledItem 0
  7038. æC 
  7039.  
  7040. æKY kHMDisabledItem
  7041. æFc Balloons.h
  7042. æT #define
  7043. æD #define kHMDisabledItem 1
  7044. æC 
  7045.  
  7046. æKY kHMCheckedItem
  7047. æFc Balloons.h
  7048. æT #define
  7049. æD #define kHMCheckedItem 2
  7050. æC 
  7051.  
  7052. æKY kHMOtherItem
  7053. æFc Balloons.h
  7054. æT #define
  7055. æD #define kHMOtherItem 3
  7056. æC 
  7057.  
  7058. æKY hdlgUseSubID
  7059. æFc Balloons.h
  7060. æT #define
  7061. æD #define hdlgUseSubID 0 /* if set then use sub ID's to fine res ID*/
  7062. æC 
  7063.  
  7064. æKY hdlgLocalCoords
  7065. æFc Balloons.h
  7066. æT #define
  7067. æD #define hdlgLocalCoords 1 /* if set then use hdlg rects as local coords, ignoring item rects*/
  7068. æC 
  7069.  
  7070. æKY hdlgSaveBits
  7071. æFc Balloons.h
  7072. æT #define
  7073. æD #define hdlgSaveBits 2 /* if set then use save bits behind balloon*/
  7074. æC 
  7075.  
  7076. æKY hwinUseResID
  7077. æFc Balloons.h
  7078. æT #define
  7079. æD 
  7080. /* Option bits for hwin resources */
  7081.  
  7082. #define hwinUseResID 0
  7083. æC 
  7084.  
  7085. æKY hwinUseSubID
  7086. æFc Balloons.h
  7087. æT #define
  7088. æD #define hwinUseSubID 1
  7089. æC 
  7090.  
  7091. æKY HMStringItem
  7092. æFc Balloons.h
  7093. æT #define
  7094. æD 
  7095. /* Constants for Help Types in 'hmnu', 'hdlg', 'hrct' resources */
  7096.  
  7097. #define HMStringItem 1
  7098. æC 
  7099.  
  7100. æKY HMPictItem
  7101. æFc Balloons.h
  7102. æT #define
  7103. æD #define HMPictItem 2
  7104. æC 
  7105.  
  7106. æKY HMStringResItem
  7107. æFc Balloons.h
  7108. æT #define
  7109. æD #define HMStringResItem 3
  7110. æC 
  7111.  
  7112. æKY HMTEResItem
  7113. æFc Balloons.h
  7114. æT #define
  7115. æD #define HMTEResItem 6
  7116. æC 
  7117.  
  7118. æKY HMSTRResItem
  7119. æFc Balloons.h
  7120. æT #define
  7121. æD #define HMSTRResItem 7
  7122. æC 
  7123.  
  7124. æKY HMSkipItem
  7125. æFc Balloons.h
  7126. æT #define
  7127. æD #define HMSkipItem 256
  7128. æC 
  7129.  
  7130. æKY HMCompareItem
  7131. æFc Balloons.h
  7132. æT #define
  7133. æD #define HMCompareItem 512
  7134. æC 
  7135.  
  7136. æKY HMNamedResourceItem
  7137. æFc Balloons.h
  7138. æT #define
  7139. æD #define HMNamedResourceItem 1024
  7140. æC 
  7141.  
  7142. æKY HMTrackCntlItem
  7143. æFc Balloons.h
  7144. æT #define
  7145. æD #define HMTrackCntlItem 2048
  7146. æC 
  7147.  
  7148. æKY khmmString
  7149. æFc Balloons.h
  7150. æT #define
  7151. æD 
  7152. /* Constants for hmmHelpType's when filling out HMMessageRecord */
  7153.  
  7154. #define khmmString 1
  7155. æC 
  7156.  
  7157. æKY khmmPict
  7158. æFc Balloons.h
  7159. æT #define
  7160. æD #define khmmPict 2
  7161. æC 
  7162.  
  7163. æKY khmmStringRes
  7164. æFc Balloons.h
  7165. æT #define
  7166. æD #define khmmStringRes 3
  7167. æC 
  7168.  
  7169. æKY khmmTEHandle
  7170. æFc Balloons.h
  7171. æT #define
  7172. æD #define khmmTEHandle 4
  7173. æC 
  7174.  
  7175. æKY khmmPictHandle
  7176. æFc Balloons.h
  7177. æT #define
  7178. æD #define khmmPictHandle 5
  7179. æC 
  7180.  
  7181. æKY khmmTERes
  7182. æFc Balloons.h
  7183. æT #define
  7184. æD #define khmmTERes 6
  7185. æC 
  7186.  
  7187. æKY khmmSTRRes
  7188. æFc Balloons.h
  7189. æT #define
  7190. æD #define khmmSTRRes 7
  7191. æC 
  7192.  
  7193. æKY kHMEnabled
  7194. æFc Balloons.h
  7195. æT #define
  7196. æD #define kHMEnabled 1
  7197. æC 
  7198.  
  7199. æKY kHMDisabled
  7200. æFc Balloons.h
  7201. æT #define
  7202. æD #define kHMDisabled 2
  7203. æC 
  7204.  
  7205. æKY kHMChecked
  7206. æFc Balloons.h
  7207. æT #define
  7208. æD #define kHMChecked 4
  7209. æC 
  7210.  
  7211. æKY kHMOther
  7212. æFc Balloons.h
  7213. æT #define
  7214. æD #define kHMOther 8
  7215. æC 
  7216.  
  7217. æKY HMTEResType
  7218. æFc Balloons.h
  7219. æT #define
  7220. æD 
  7221. /* ResTypes for Styled TE Handles when extracting from Resources */
  7222.  
  7223. #define HMTEResType 'thdl'
  7224. æC 
  7225.  
  7226. æKY HMTEStyleType
  7227. æFc Balloons.h
  7228. æT #define
  7229. æD #define HMTEStyleType 'tsty'
  7230. æC 
  7231.  
  7232. æKY HMSTHandleType
  7233. æFc Balloons.h
  7234. æT #define
  7235. æD #define HMSTHandleType 'tstb'
  7236. æC 
  7237.  
  7238. æKY HMLHHandleType
  7239. æFc Balloons.h
  7240. æT #define
  7241. æD #define HMLHHandleType 'thtb'
  7242. æC 
  7243.  
  7244. æKY HMStringResType
  7245. æFc Balloons.h
  7246. æT struct
  7247. æD struct HMStringResType {
  7248.     short hmmResID;
  7249.     short hmmIndex;
  7250. };
  7251.  
  7252. typedef struct HMStringResType HMStringResType;
  7253. æC 
  7254.  
  7255. æKY HMStringMsgRecord
  7256. HMStringMsgRecPtr
  7257. æFc Balloons.h
  7258. æT struct
  7259. æD struct HMStringMsgRecord {
  7260.     short hmmHelpType;
  7261.     Str255 hmmString;
  7262. };
  7263.  
  7264. typedef struct HMStringMsgRecord HMStringMsgRecord;
  7265. typedef HMStringMsgRecord *HMStringMsgRecPtr;
  7266.  
  7267. æC 
  7268.  
  7269. æKY HMPictMsgRecord
  7270. HMPictMsgRecPtr
  7271. æFc Balloons.h
  7272. æT struct
  7273. æD struct HMPictMsgRecord {
  7274.     short hmmHelpType;
  7275.     short hmmPict;
  7276.     char fill[254];
  7277. };
  7278.  
  7279. typedef struct HMPictMsgRecord HMPictMsgRecord;
  7280. typedef HMPictMsgRecord *HMPictMsgRecPtr;
  7281.  
  7282. æC 
  7283.  
  7284. æKY HMTEHMsgRecord
  7285. HMTEHMsgRecPtr
  7286. æFc Balloons.h
  7287. æT struct
  7288. æD struct HMTEHMsgRecord {
  7289.     short hmmHelpType;
  7290.     Handle hmmTEHandle;
  7291.     char fill[252];
  7292. };
  7293.  
  7294. typedef struct HMTEHMsgRecord HMTEHMsgRecord;
  7295. typedef HMTEHMsgRecord *HMTEHMsgRecPtr;
  7296.  
  7297. æC 
  7298.  
  7299. æKY HMStrResMsgRecord
  7300. HMStrResMsgRecPtr
  7301. æFc Balloons.h
  7302. æT struct
  7303. æD struct HMStrResMsgRecord {
  7304.     short hmmHelpType;
  7305.     HMStrResType hmmStrRes;
  7306.     char fill[250];
  7307. };
  7308.  
  7309. typedef struct HMStrResMsgRecord HMStrResMsgRecord;
  7310. typedef HMStrResMsgRecord *HMStrResMsgRecPtr;
  7311.  
  7312. æC 
  7313.  
  7314. æKY HMPicHMsgRecord
  7315. HMPicHMsgRecPtr
  7316. æFc Balloons.h
  7317. æT struct
  7318. æD struct HMPicHMsgRecord {
  7319.     short hmmHelpType;
  7320.     PicHandle hmmPicHandle;
  7321.     char fill[252];
  7322. };
  7323.  
  7324. typedef struct HMPicHMsgRecord HMPicHMsgRecord;
  7325. typedef HMPicHMsgRecord *HMPicHMsgRecPtr;
  7326.  
  7327. æC 
  7328.  
  7329. æKY HMDefaultRecord
  7330. HMDefaultRecPtr
  7331. æFc Balloons.h
  7332. æT struct
  7333. æD struct HMDefaultRecord {
  7334.     short hmVersion;
  7335.     HMStringMsgRecord hmDefMessage;
  7336.     short hmHelpVRefNum;
  7337.     long hmHelpDirID;
  7338.     Boolean hmSearchAlternateFiles;
  7339. };
  7340.  
  7341. typedef struct HMDefaultRecord HMDefaultRecord;
  7342. typedef HMDefaultRecord *HMDefaultRecPtr;
  7343.  
  7344. æC 
  7345.  
  7346. æKY HMStringDefaultRecord
  7347. HMStringDefaultRecPtr
  7348. æFc Balloons.h
  7349. æT struct
  7350. æD struct HMStringDefaultRecord {
  7351.     short hmVersion;
  7352.     HMStringMsgRecord hmDefMessage;
  7353.     short hmHelpVRefNum;
  7354.     long hmHelpDirID;
  7355.     Boolean hmSearchAlternateFiles;
  7356. };
  7357.  
  7358. typedef struct HMStringDefaultRecord HMStringDefaultRecord;
  7359. typedef HMStringDefaultRecord *HMStringDefaultRecPtr;
  7360.  
  7361. æC 
  7362.  
  7363. æKY HMPictDefaultRecord
  7364. HMPictDefaultRecPtr
  7365. æFc Balloons.h
  7366. æT struct
  7367. æD struct HMPictDefaultRecord {
  7368.     short hmVersion;
  7369.     HMPictMsgRecord hmDefMessage;
  7370.     short hmHelpVRefNum;
  7371.     long hmHelpDirID;
  7372.     Boolean hmSearchAlternateFiles;
  7373. };
  7374.  
  7375. typedef struct HMPictDefaultRecord HMPictDefaultRecord;
  7376. typedef HMPictDefaultRecord *HMPictDefaultRecPtr;
  7377.  
  7378. æC 
  7379.  
  7380. æKY HMTEHDefaultRecord
  7381. HMTEHDefaultRecPtr
  7382. æFc Balloons.h
  7383. æT struct
  7384. æD struct HMTEHDefaultRecord {
  7385.     short hmVersion;
  7386.     HMTEHMsgRecord hmDefMessage;
  7387.     short hmHelpVRefNum;
  7388.     long hmHelpDirID;
  7389.     Boolean hmSearchAlternateFiles;
  7390. };
  7391.  
  7392. typedef struct HMTEHDefaultRecord HMTEHDefaultRecord;
  7393. typedef HMTEHDefaultRecord *HMTEHDefaultRecPtr;
  7394.  
  7395. æC 
  7396.  
  7397. æKY HMStrResDefaultRecord
  7398. HMStrResDefaultRecPtr
  7399. æFc Balloons.h
  7400. æT struct
  7401. æD struct HMStrResDefaultRecord {
  7402.     short hmVersion;
  7403.     HMStrResMsgRecord hmDefMessage;
  7404.     short hmHelpVRefNum;
  7405.     long hmHelpDirID;
  7406.     Boolean hmSearchAlternateFiles;
  7407. };
  7408.  
  7409. typedef struct HMStrResDefaultRecord HMStrResDefaultRecord;
  7410. typedef HMStrResDefaultRecord *HMStrResDefaultRecPtr;
  7411.  
  7412. æC 
  7413.  
  7414. æKY HMPicHDefaultRecord
  7415. HMPicHDefaultRecPtr
  7416. æFc Balloons.h
  7417. æT struct
  7418. æD struct HMPicHDefaultRecord {
  7419.     short hmVersion;
  7420.     HMPicHMsgRecord hmDefMessage;
  7421.     short hmHelpVRefNum;
  7422.     long hmHelpDirID;
  7423.     Boolean hmSearchAlternateFiles;
  7424. };
  7425.  
  7426. typedef struct HMPicHDefaultRecord HMPicHDefaultRecord;
  7427. typedef HMPicHDefaultRecord *HMPicHDefaultRecPtr;
  7428.  
  7429. æC 
  7430.  
  7431. æKY HMStringRecord
  7432. æFc Balloons.h
  7433. æT struct
  7434. æD struct HMStringRecord {
  7435.     short hmmHelpType;
  7436.     short hmmFont;
  7437.     short hmmFontSize;
  7438.     char hmmMessage[256];
  7439. };
  7440.  
  7441. typedef struct HMStringRecord HMStringRecord;
  7442. æC 
  7443.  
  7444. æKY HMMessageRecord
  7445. HMMessageRecordPtr
  7446. æFc Balloons.h
  7447. æT struct
  7448. æD union HMMessageRecord {
  7449.     HMStringMsgRecord HMStringMsg;
  7450.     HMPictMsgRecord HMPictMsg;
  7451.     HMTEHMsgRecord HMTEHMsg;
  7452.     HMStrResMsgRecord HMStrResMsg;
  7453.     HMResSTRMsgRecord HMResSTRMsg;
  7454.     HMPicHMsgRecord HMPicHMsg;
  7455. };
  7456.  
  7457. typedef union HMMessageRecord HMMessageRecord;
  7458.  
  7459. typedef HMMessageRecord *HMMessageRecordPtr;
  7460.  
  7461. æC 
  7462.  
  7463. æKY HMShowBalloon
  7464. æFc Balloons.h
  7465. æT Function
  7466. æD pascal short HMShowBalloon(const HMMessageRecord *aHelpMsg,Point tip,Rect *alternateRect,
  7467.     Ptr tipProc,short theProc,short variant,Boolean saveBits)
  7468.     = {0x303C,0x0B01,_Pack14}; 
  7469. æDT short myVariable = HMShowBalloon((const HMMessageRecord *) aHelpMsg,(Point) tip,(Rect *) alternateRect,()
  7470.     Ptr tipProc,(short) theProc,(short) variant,(Boolean) saveBits);
  7471. æC 
  7472. If help is enabled, you can use the HMShowBalloon function to display a balloon
  7473. containing the message specified by the message parameter; the balloon’s tip is
  7474. located at the point specified by the tip parameter.
  7475.  
  7476. Use the HMShowBalloon function to display a help message for an item that the
  7477. user can move. Use the HMShowMenuBalloon function to display help messages for
  7478. your application’s non-standard menus.
  7479.  
  7480. Parameter  Description
  7481. message    specifies the help message to be displayed. The HMMessageRecord
  7482.            data type is described in “The Help Message Record” earlier
  7483.            in this chapter.
  7484.  
  7485. tip        specifies, in global coordinates, the point where you want to 
  7486.            position the balloon’s tip.  For additional information about how 
  7487.            the Help Manager positions balloons, see “How the Help Manager 
  7488.            Positions the Help Balloon” earlier in this chapter.
  7489.  
  7490. hotRect    defines the area for which a specific help message is owned. That
  7491.            is, if the user moves the cursor anywhere outside the area specified
  7492.            by the hotRect parameter (once a balloon has been displayed), the
  7493.            Help Manager will remove the balloon This area is also the area of
  7494.            drift for the balloon tip. That is, if your specification for the
  7495.            tip parameter would force the Help Manager to position a balloon so
  7496.            that it obscures the element to be explained or so that it spills 
  7497.            off the screen, the Help Manager attempts to relocate the tip within
  7498.            the area defined by the hotRect parameter. See “How the Help Manager
  7499.            Positions the Help Balloon” earlier in this chapter for additional
  7500.            information.
  7501.  
  7502. tipProc    specifies the address of a procedure you write that tests the 
  7503.            values of the tip position and the balloon rectangle calculated by 
  7504.            the Help Manager. You would write such a procedure if you anticipated
  7505.            problems positioning a help balloon. Using this function gives the 
  7506.            application one more chance to modify the balloon’s position or
  7507.            dimensions before displaying it.  Pass NIL for the tipProc parameter
  7508.            if you want the Help Manager to ignore the HMBaloonHook function. For
  7509.            additional information, see “Testing the Tip Position and the 
  7510.            Dimensions of the Help Balloon” earlier in this chapter for 
  7511.            additional information.
  7512.  
  7513. theProc    specifies the resource ID of the window definition procedure
  7514.            that you want the Help Manager to use to define the help balloon 
  7515.            shape. The Help Manager reads the ‘WDEF’ resource into memory if it’s
  7516.            not already in memory.  If the Help Manager cannot find or read the
  7517.            resource, the balloon is not displayed and the function returns the
  7518.            system error -192, resNotFound. To use the Help Manager’s default
  7519.            balloon shape, pass 0 for both the procedure and the variant 
  7520.            parameter.
  7521.  
  7522. variant    specifies the variation code for the window definition
  7523.            procedure specified by the parameter theProc. If you specify 0 
  7524.            for the parameter theProc, you can still specify a value for 
  7525.            variant to indicate a preferred tip position for the default
  7526.            balloon. See "Defining Your Own Balloon Shape" earlier in 
  7527.            this chapter for additional information.
  7528.  
  7529. saveBits   a value of TRUE specifies that the Help Manager should save the
  7530.            bits behind the balloon.  Only use the saveBits option if you are
  7531.            certain that the bits behind the balloon will still be valid when
  7532.            the balloon is removed; as would be the case, for example, with 
  7533.            the bits behind a pulled down menu.  
  7534.            
  7535.            A value of FALSE specifies that the Window Manager should generate
  7536.            an update event for the window behind the balloon when you remove the
  7537.  
  7538.            balloon.
  7539.  
  7540.            You must specify FALSE for saveBits if the parameter theProc is
  7541.            non-zero,that is, if you are defining your own balloon shape.
  7542.  
  7543. The HMShowBalloon function returns the noErr result if the Help Manager displays
  7544. a balloon. If help was disabled or if no balloon was displayed, the function
  7545. returns a non-zero result.
  7546.  
  7547. Result codes
  7548. noErr                      0  No error
  7549. paramErr                 –50  Bad parameters passed in message record
  7550. memFullErr              –108  Not enough room in heap zone
  7551. resNotFound             –192  The balloon ‘WDEF’ could not be read
  7552. hmHelpDisabled          –850  Help is disabled
  7553. hmBalloonAborted        –853  Cursor was not stationary
  7554. hmCouldnotLoadPackage   –860  There was not enough memory to load
  7555.                               package
  7556. hmOperationUnsupported  –861  Could not interpret call
  7557.  
  7558. æKY HMRemoveBalloon
  7559. æFc Balloons.h
  7560. æT Function
  7561. æD pascal short HMRemoveBalloon(void)
  7562.     = {0x303C,0x0002,_Pack14}; 
  7563. æDT short myVariable = HMRemoveBalloon()(void);
  7564. æC 
  7565. The HMRemoveBalloon function removes any help message that is currently visible.
  7566. If no help message is visible, the HMRemoveBalloon function does nothing.  Use
  7567. the HMRemoveBalloon function to remove balloons created either by HMShowBalloon
  7568. or HMShowMenuBalloon. 
  7569.  
  7570. If a balloon is visible and the user disables help, the Help Manager calls this
  7571. function automatically.  The Help Manager also calls the HMRemoveBalloon
  7572. function so that no more than one help balloon is displayed at any time. Thus if
  7573. your application makes successive calls to show balloons without calling the
  7574. HMRemoveBalloon function, the Help Manager calls the HMRemoveBalloon function
  7575. automatically to remove the first balloon before displaying the second balloon.
  7576.  
  7577. If your application has called the HMShowBalloon function to display a help
  7578. message and the hotRect parameter was NIL, call the HMRemoveBalloon function
  7579. when the cursor moves out of the specified area. In a customized 'MDEF'
  7580. definition procedure, call the HMRemoveBalloon function before hiding a drawn
  7581. menu. In a customized 'MBDF' procedure, call the HMRemoveBalloon function in
  7582. response to the messages SaveBits and RestoreBits before saving or restoring any
  7583. bits.
  7584.  
  7585. Results codes
  7586. noErr                      0  No error; a balloon was removed
  7587. paramErr                 –50  Bad parameters passed in message record
  7588. hmHelpDisabled          –850  Balloon help is disabled
  7589. hmCouldnotLoadPackage   –860  There was not enough memory to load
  7590.                               package
  7591. hmOperationUnsupported  –861  Could not interpret call
  7592.  
  7593. æKY HMGetBalloons
  7594. æFc Balloons.h
  7595. æT Function
  7596. æD pascal Boolean HMGetBalloons(void)
  7597.     = {0x303C,0x0003,_Pack14}; 
  7598. æDT Boolean myVariable = HMGetBalloons()(void);
  7599. æC 
  7600. The HMGetBalloons function returns the current setting of the flag parameter for
  7601. the HMSetBalloons function.
  7602.  
  7603. æKY HMSetBalloons
  7604. æFc Balloons.h
  7605. æT Function
  7606. æD pascal Short HMSetBalloons(Boolean flag)
  7607.     = {0x303C,0x0104,_Pack14}; 
  7608. æDT Short myVariable = HMSetBalloons((Boolean) flag);
  7609. æC 
  7610. Calling the HMSetBalloons function activates the Help Manager if the value of
  7611. the flag parameter is TRUE and turns it off if the value of flag is FALSE.  When
  7612. help is enabled, the Help Manager automatically displays balloons for standard
  7613. window parts and system dialog boxes. Disabling help removes any balloon
  7614. displayed by calls to the HMShowBalloon or HMShowMenuBalloon functions. 
  7615.  
  7616. Result codes
  7617. noErr                     0  No error
  7618. hmCouldnotLoadPackage  –860  There was not enough memory to load
  7619.                               package
  7620. hmOperationUnsupported  –861  Could not interpret call
  7621.  
  7622. æKY HMShowMenuBalloon
  7623. æFc Balloons.h
  7624. æT Function
  7625. æD pascal short HMShowMenuBalloon(short itemNum,short itemMenuID,long itemFlags,
  7626.     long itemReserved,Point tip,Ptr alternateRect,Ptr tipProc,short theProc,
  7627.     short variant)
  7628.     = {0x303C,0x0E05,_Pack14}; 
  7629. æDT short myVariable = HMShowMenuBalloon((short) itemNum,(short) itemMenuID,(long) itemFlags,()
  7630.     long itemReserved,(Point) tip,(Ptr) alternateRect,(Ptr) tipProc,(short) theProc,()
  7631.     short variant);
  7632. æC 
  7633. The HMShowMenuBalloon function allows you to display help balloons for an
  7634. application's non-standard menu. You call the HMShowMenuBalloon function from 
  7635. a menu’s ‘MDEF’ definition procedure right after drawing, highlighting, or
  7636. determining that the cursor is over a menu item.
  7637.  
  7638. Parameter   Description
  7639. itemNum     specifies the number of the menu item to which the cursor is 
  7640.             pointing. If the cursor points to the menu title, the itemNum 
  7641.             parameter contains 0;if the cursor points to a dashed line, the 
  7642.             itemNum parameter contains -1.
  7643.  
  7644. itemMenuID  specifies the menuID of the menu currently in use.
  7645.  
  7646. itemFlags   specifies the menu's enabledFlags Longword, which tells the Help
  7647.             Manager whether the menu item is enabled or disabled. The Help 
  7648.             Manager uses this value to select the corresponding message
  7649.             from the ‘hmnu’ resource associated with the menu specified by 
  7650.             itemMenuID.
  7651.  
  7652. itemReserved  reserved for future expansion; specify 0
  7653.  
  7654. tip         specifies, in global coordinates, the point where you want the
  7655.             balloon’s tip.  For additional information about how the Help 
  7656.             Manager positions balloons, see “How the Help Manager Positions 
  7657.             the Help Balloon” earlier in this chapter.
  7658.  
  7659. hotRect     specifies the area of drift for the balloon tip. That is, if
  7660.             your specification for the tip parameter would force the Help
  7661.             Manager to position a balloon so that it obscures the element to 
  7662.             be explained or so that it spills off the screen, the Help Manager
  7663.             attempts to relocate the tip within the area defined by the
  7664.             hotRect.parameter. See “How the Help Manager Positions the Help 
  7665.             Balloon” earlier in this chapter for additional information.
  7666.  
  7667. tipProc     specifies the address of a procedure you write that tests the
  7668.             values of the tip position and the balloon rectangle calculated by
  7669.             the Help Manager. You would write such a procedure if you 
  7670.             anticipated problems positioning a help balloon.  Using this
  7671.             function gives the application one more chance to modify the 
  7672.             balloon’s position or the dimensions of the balloon before 
  7673.             displaying it. Pass NIL for the tipProc parameter if you want the 
  7674.             Help Manager to ignore the HMBaloonHook function. For additional
  7675.             information, see “Changing the Tip Position and the Dimensions of
  7676.             the Help Balloon” earlier in this chapter for additional
  7677.             information.
  7678.  
  7679. reserved    specify 0.
  7680.  
  7681. reserved    specify 0.
  7682.  
  7683. Result codes
  7684. noErr                      0  No error
  7685. paramErr                 –50  Bad parameters passed in message record
  7686. memFullErr              –108  Not enough room in heap zone
  7687. resNotFound             –192  'hmnu' resource could not be read
  7688. hmHelpDisabled          –850  Balloon help is disabled
  7689. hmCouldnotLoadPackage   –860  There was not enough memory to load
  7690.        package
  7691. hmOperationUnsupported  –861  Could not interpret call
  7692.  
  7693. æKY HMMouseInApplRgn
  7694. æFc Balloons.h
  7695. æT Function
  7696. æD pascal Boolean HMMouseInApplRgn(void)
  7697.     = {0x303C,0x0006,_Pack14}; 
  7698. æDT Boolean myVariable = HMMouseInApplRgn()(void);
  7699. æC 
  7700.  
  7701. æKY HMIsBalloon
  7702. æFc Balloons.h
  7703. æT Function
  7704. æD pascal Boolean HMIsBalloon(void)
  7705.     = {0x303C,0x0007,_Pack14}; 
  7706. æDT Boolean myVariable = HMIsBalloon()(void);
  7707. æC 
  7708. The HMIsBalloon function determines whether a help balloon is currently showing.
  7709. A return value of TRUE means that a balloon is showing; a value of FALSE means
  7710. that no balloon is showing.
  7711.  
  7712. æKY HMSetFont
  7713. æFc Balloons.h
  7714. æT Function
  7715. æD pascal Short HMSetFont(short font)
  7716.     = {0x303C,0x0108,_Pack14}; 
  7717. æDT Short myVariable = HMSetFont((short) font);
  7718. æC 
  7719.  
  7720. æKY HMSetFontSize
  7721. æFc Balloons.h
  7722. æT Function
  7723. æD pascal Short HMSetFontSize(short fontsize)
  7724.     = {0x303C,0x0109,_Pack14}; 
  7725. æDT Short myVariable = HMSetFontSize((short) fontsize);
  7726. æC 
  7727.  
  7728. æKY HMGetFont
  7729. æFc Balloons.h
  7730. æT Function
  7731. æD pascal Short HMGetFont(short *font)
  7732.     = {0x303C,0x020A,_Pack14}; 
  7733. æDT Short myVariable = HMGetFont((short *) font);
  7734. æC 
  7735.  
  7736. æKY HMGetFontSize
  7737. æFc Balloons.h
  7738. æT Function
  7739. æD pascal Short HMGetFontSize(short *fontSize)
  7740.     = {0x303C,0x020B,_Pack14}; 
  7741. æDT Short myVariable = HMGetFontSize((short *) fontSize);
  7742. æC 
  7743.  
  7744. æKY HMSetDialogResID
  7745. æFc Balloons.h
  7746. æT Function
  7747. æD pascal Short HMSetDialogResID(short resID)
  7748.     = {0x303C,0x010C,_Pack14}; 
  7749. æDT Short myVariable = HMSetDialogResID((short) resID);
  7750. æC 
  7751. You can use the HMSetDialogResID function in two ways:
  7752.  
  7753. 1.  If a dialog or alert item list  ('DITL') does not include a helpItem
  7754.     specifying an 'hdlg' ID that the Help Manager should use to display
  7755.     help messages, calling the HMSetDialogResID function just before 
  7756.     displaying the dialog or alert box tells the Help Manager to display help
  7757.     messages stored in the 'hdlg' resource whose ID is specified by resID.
  7758.  
  7759. 2.  If a dialog or alert item list does include a helpItem, you call the
  7760.     HMSetDialogResID function just before displaying the dialog or alert box
  7761.     to override the 'hdlg' ID resource specified in the helpItem field. 
  7762.     Call the HMSetDialogResID function with a resID value of -1 after displaying
  7763.     the alert or dialog box to clear (reset) the first call.
  7764.  
  7765. Result codes
  7766. noErr                      0  No error
  7767. memFullErr              –108  Not enough room in the heap zone
  7768. resNotFound             –192  'hdlg' resource could not be read  
  7769. hmCouldnotLoadPackage   –860  There was not enough memory to load pacage
  7770. hmOperationUnsupported  –861  Could not interpret call
  7771.  
  7772. æKY HMSetMenuResID
  7773. æFc Balloons.h
  7774. æT Function
  7775. æD pascal Short HMSetMenuResID(short menuID,short resID)
  7776.     = {0x303C,0x020D,_Pack14}; 
  7777. æDT Short myVariable = HMSetMenuResID((short) menuID,(short) resID);
  7778. æC 
  7779. The HMSetMenuResID function overrides the ‘hmnu’ resource ID used to provide
  7780. help text for a particular menu.
  7781.  
  7782. The menuID parameter specifies an existing menu ID in the application’s menu
  7783. list.  The resID parameter specifies a ‘hmnu’ resource ID that is to be used in
  7784. place of the ‘hmnu’ resource normally used to provide help for the specified
  7785. menu.
  7786.  
  7787. If the menuID is not in the menu list, the function does nothing.
  7788.  
  7789. To dissociate the menu specified by menuID from the resource specified by resID,
  7790. specify -1 for the resID parameter.
  7791.  
  7792. Result codes
  7793. noErr                      0  No error
  7794. memFullErr              –108  Not enough room in the heap zone
  7795. resNotFound             –192  'hdlg' resource could not be read  
  7796. hmCouldnotLoadPackage   –860  There was not enough memory to load package
  7797. hmOperationUnsupported  –861  Could not interpret call
  7798.  
  7799. æKY HMBalloonRect
  7800. æFc Balloons.h
  7801. æT Function
  7802. æD pascal Short HMBalloonRect(const HMMessageRecord *aHelpMsg,Rect *coolRect)
  7803.     = {0x303C,0x040E,_Pack14}; 
  7804. æDT Short myVariable = HMBalloonRect((const HMMessageRecord *) aHelpMsg,(Rect *) coolRect);
  7805. æC 
  7806. The HMBalloonRect function returns a rectangle in the coolRect parameter that is
  7807. just the right size to display the text message specified by the aHelpMessage
  7808. parameter.
  7809.  
  7810. See “Providing Help for Application-Specific Elements” earlier in this chapter
  7811. for a description of the HMMessageRecord data type.
  7812.  
  7813. Result codes
  7814. noErr                           0  No Error
  7815. paramErr                      –50  Bad parameters passed in message
  7816.  memFullErr                  –108  Not enough room in heap zone
  7817. recordhmCouldnotLoadPackage  –860  There was not enough memory to load package 
  7818.  
  7819. hmOperationUnsupported       –861  Could not interpret call
  7820.  
  7821. æKY HMBaloonPict
  7822. æFc Balloons.h
  7823. æT Function
  7824. æD pascal Short HMBaloonPict(const HMMessageRecord *aHelpMsg,Handle *coolPict)
  7825.     = {0x303C,0x040F,_Pack14}; 
  7826. æDT Short myVariable = HMBaloonPict((const HMMessageRecord *) aHelpMsg,(Handle *) coolPict);
  7827. æC 
  7828. The HMBalloonPict function returns a handle to a picture that shows how the text
  7829. contained in aHelpMessage is going to be displayed.
  7830.  
  7831. Result codes
  7832. noErr                      0  No Error
  7833. paramErr                 –50  Bad parameters passed in message
  7834.  memFullErr             –108  Not enough room in heap zone
  7835. hmCouldnotLoadPackage   –860  There was not enough memory to load package
  7836. hmOperationUnsupported  –861  Could not interpret call
  7837.  
  7838. æKY HMScanTemplateItems
  7839. æFc Balloons.h
  7840. æT Function
  7841. æD pascal Short HMScanTemplateItems(Short whichID,Short whichResFile,ResType whichType)
  7842.     = {0x303C,0x0410,_Pack14}; 
  7843. æDT Short myVariable = HMScanTemplateItems((Short) whichID,(Short) whichResFile,(ResType) whichType);
  7844. æC 
  7845. You use this function when you have no other way of associating a dialog box or
  7846. window with an 'hdlg' or 'hrct' resource. This might happen because you have a
  7847. dialog box with a changing title and a fixed item list or because you want to
  7848. supply help for areas of a window whose title changes.
  7849.  
  7850. When you call this function the Help Manager will provide help messages (for the
  7851. frontmost window) from the resource whose type you specify with the whichType
  7852. parameter and whose ID you specify using the which ID parameter. The resource
  7853. must reside in the file specified by the whichResFile parameter and this file
  7854. must be open.
  7855.  
  7856. The whichType parameter specifies the type of the resource and must be either
  7857. 'hdlg' or 'hrct'.
  7858.  
  7859. Result codes
  7860. noErr                      0  No error
  7861. fnOpenErr                –38  Resource file was not open
  7862. paramErr                 –50  Bad parameters passed in message record
  7863. memFullErr              –108  Not enough room in heap zone
  7864. resnotFound             –192  'hmnu' resource could not be read
  7865. hmHelpDisabled          –850  Balloon help is disabled
  7866. hmCouldnotLoadPackage   –860  There was not enough memory to load
  7867.        package
  7868. hmOperationUnsupported  –861  Could not interpret call
  7869.  
  7870. æKY HMExtractHelpMsg
  7871. æFc Balloons.h
  7872. æT Function
  7873. æD pascal Short HMExtractHelpMsg(ResType whichType,Short whichResID,Short whichMsg,
  7874.     Short whichState,HMMessageRecord *aHelpMsg)
  7875.     = {0x303C,0x0711,_Pack14}; 
  7876. æDT Short myVariable = HMExtractHelpMsg((ResType) whichType,(Short) whichResID,(Short) whichMsg,()
  7877.     Short whichState,(HMMessageRecord *) aHelpMsg);
  7878. æC 
  7879.  
  7880. æKY HMFillCitationString
  7881. æFc Balloons.h
  7882. æT Function
  7883. æD pascal Short HMFillCitationString(StringPtr origString,StringPtr stuffString,
  7884.     Short key)
  7885.     = {0x303C,0x0512,_Pack14}; 
  7886. æDT Short myVariable = HMFillCitationString((StringPtr) origString,(StringPtr) stuffString,()
  7887.     Short key);
  7888. æC 
  7889.  
  7890. æKY HMGetDialogResID
  7891. æFc Balloons.h
  7892. æT Function
  7893. æD pascal Short HMGetDialogResID(short *resID)
  7894.     = {0x303C,0x0213,_Pack14}; 
  7895. æDT Short myVariable = HMGetDialogResID((short *) resID);
  7896. æC 
  7897. The HMGetDialogResID function returns the 'hdlg' resource ID that the Help
  7898. Manager is currently using to provide help messages for a dialog box. If there
  7899. is no current resource, resID contains -1.
  7900.  
  7901. Result codes
  7902. noErr                      0  No error
  7903. memFullErr              –108  Not enough room in the heap zone
  7904. resNotFound             –192  'hdlg' resource could not be read  
  7905. hmCouldnotLoadPackage   –860  There was not enough memory to load package
  7906. hmOperationUnsupported  –861  Could not interpret call
  7907.  
  7908. æKY HMGetMenuResID
  7909. æFc Balloons.h
  7910. æT Function
  7911. æD pascal Short HMGetMenuResID(short menuID,short *resID)
  7912.     = {0x303C,0x0314,_Pack14}; 
  7913. æDT Short myVariable = HMGetMenuResID((short) menuID,(short *) resID);
  7914. æC 
  7915. The HMGetMenuResID function returns the ID of the 'hmnu' resource that the Help
  7916. Manager is currently associating with the menu whose ID you specify for the
  7917. menuID parameter.
  7918.   
  7919. Result codes
  7920. noErr                      0  No error
  7921. memFullErr              –108  Not enough room in the heap zone
  7922. resNotFound             –192  'hdlg' resource could not be read  
  7923. hmCouldnotLoadPackage   –860  There was not enough memory to load package
  7924. hmOperationUnsupported  –861  Could not interpret call
  7925.  
  7926.  
  7927. æKY Controls.h
  7928. æKL DisposeControl
  7929. dragcontrol
  7930. DragControl
  7931. Draw1Control
  7932. DrawControls
  7933. findcontrol
  7934. FindControl
  7935. GetAuxCtl
  7936. GetCRefCon
  7937. GetCTitle
  7938. getctitle
  7939. GetCtlAction
  7940. GetCtlMax
  7941. GetCtlMin
  7942. GetCtlValue
  7943. GetCVariant
  7944. GetNewControl
  7945. HideControl
  7946. HiliteControl
  7947. KillControls
  7948. MoveControl
  7949. newcontrol
  7950. NewControl
  7951. SetCRefCon
  7952. SetCTitle
  7953. setctitle
  7954. SetCtlAction
  7955. SetCtlColor
  7956. SetCtlMax
  7957. SetCtlMin
  7958. SetCtlValue
  7959. ShowControl
  7960. SizeControl
  7961. testcontrol
  7962. TestControl
  7963. TrackControl
  7964. trackcontrol
  7965. UpdtControl
  7966.  
  7967. autoTrack
  7968. AuxCtlHandle
  7969. AuxCtlPtr
  7970. AuxCtlRec
  7971. calcCntlRgn
  7972. calcCRgns
  7973. calcThumbRgn
  7974. cBodyColor
  7975. CCTabHandle
  7976. CCTabPtr
  7977. cFrameColor
  7978. checkBoxProc
  7979. ControlHandle
  7980. ControlPtr
  7981. ControlRecord
  7982. cTextColor
  7983. cThumbColor
  7984. CtlCTab
  7985. dispCntl
  7986. dragCntl
  7987. drawCntl
  7988. hAxisOnly
  7989. inButton
  7990. inCheckBox
  7991. inDownButton
  7992. initCntl
  7993. inLabel
  7994. inMenu
  7995. inPageDown
  7996. inPageUp
  7997. inThumb
  7998. inTriangle
  7999. inUpButton
  8000. noConstraint
  8001. popupMenuProc
  8002. popupTitleCenterJust
  8003. popupTitleLeftJust
  8004. popupTitleRightJust
  8005. posCntl
  8006. pushButProc
  8007. radioButProc
  8008. scrollBarProc
  8009. testCntl
  8010. thumbCntl
  8011. useWFont
  8012. vAxisOnly
  8013.  
  8014. æKY pushButProc
  8015. æFc Controls.h
  8016. æT #define
  8017. æD #define pushButProc 0
  8018. æC 
  8019.  
  8020. æKY checkBoxProc
  8021. æFc Controls.h
  8022. æT #define
  8023. æD #define checkBoxProc 1
  8024. æC 
  8025.  
  8026. æKY radioButProc
  8027. æFc Controls.h
  8028. æT #define
  8029. æD #define radioButProc 2
  8030. æC 
  8031.  
  8032. æKY useWFont
  8033. æFc Controls.h
  8034. æT #define
  8035. æD #define useWFont 8
  8036. æC 
  8037.  
  8038. æKY scrollBarProc
  8039. æFc Controls.h
  8040. æT #define
  8041. æD #define scrollBarProc 16
  8042. æC 
  8043.  
  8044. æKY inButton
  8045. æFc Controls.h
  8046. æT #define
  8047. æD #define inButton 10
  8048. æC 
  8049.  
  8050. æKY inCheckBox
  8051. æFc Controls.h
  8052. æT #define
  8053. æD #define inCheckBox 11
  8054. æC 
  8055.  
  8056. æKY inUpButton
  8057. æFc Controls.h
  8058. æT #define
  8059. æD #define inUpButton 20
  8060. æC 
  8061.  
  8062. æKY inDownButton
  8063. æFc Controls.h
  8064. æT #define
  8065. æD #define inDownButton 21
  8066. æC 
  8067.  
  8068. æKY inPageUp
  8069. æFc Controls.h
  8070. æT #define
  8071. æD #define inPageUp 22
  8072. æC 
  8073.  
  8074. æKY inPageDown
  8075. æFc Controls.h
  8076. æT #define
  8077. æD #define inPageDown 23
  8078. æC 
  8079.  
  8080. æKY inThumb
  8081. æFc Controls.h
  8082. æT #define
  8083. æD #define inThumb 129
  8084. æC 
  8085.  
  8086. æKY popupMenuProc
  8087. æFc Controls.h
  8088. æT #define
  8089. æD #define popupMenuProc 1008 /* 63 * 16 */
  8090. æC 
  8091.  
  8092. æKY inLabel
  8093. æFc Controls.h
  8094. æT #define
  8095. æD #define inLabel 1
  8096. æC 
  8097.  
  8098. æKY inMenu
  8099. æFc Controls.h
  8100. æT #define
  8101. æD #define inMenu 2
  8102. æC 
  8103.  
  8104. æKY inTriangle
  8105. æFc Controls.h
  8106. æT #define
  8107. æD #define inTriangle 4
  8108. æC 
  8109.  
  8110. æKY popupTitleLeftJust
  8111. æFc Controls.h
  8112. æT #define
  8113. æD #define popupTitleLeftJust 0x0000
  8114. æC 
  8115.  
  8116. æKY popupTitleCenterJust
  8117. æFc Controls.h
  8118. æT #define
  8119. æD #define popupTitleCenterJust 0x0001
  8120. æC 
  8121.  
  8122. æKY popupTitleRightJust
  8123. æFc Controls.h
  8124. æT #define
  8125. æD #define popupTitleRightJust 0x00FF
  8126. æC 
  8127.  
  8128. æKY noConstraint
  8129. æFc Controls.h
  8130. æT #define
  8131. æD 
  8132. /* 
  8133. axis constraints for DragGrayRgn call */
  8134.  
  8135. #define noConstraint 0
  8136. æC 
  8137.  
  8138. æKY hAxisOnly
  8139. æFc Controls.h
  8140. æT #define
  8141. æD #define hAxisOnly 1
  8142. æC 
  8143.  
  8144. æKY vAxisOnly
  8145. æFc Controls.h
  8146. æT #define
  8147. æD #define vAxisOnly 2
  8148. æC 
  8149.  
  8150. æKY drawCntl
  8151. æFc Controls.h
  8152. æT #define
  8153. æD 
  8154. /* 
  8155. control messages */
  8156.  
  8157. #define drawCntl 0
  8158. æC 
  8159.  
  8160. æKY testCntl
  8161. æFc Controls.h
  8162. æT #define
  8163. æD #define testCntl 1
  8164. æC 
  8165.  
  8166. æKY calcCRgns
  8167. æFc Controls.h
  8168. æT #define
  8169. æD #define calcCRgns 2
  8170. æC 
  8171.  
  8172. æKY initCntl
  8173. æFc Controls.h
  8174. æT #define
  8175. æD #define initCntl 3
  8176. æC 
  8177.  
  8178. æKY dispCntl
  8179. æFc Controls.h
  8180. æT #define
  8181. æD #define dispCntl 4
  8182. æC 
  8183.  
  8184. æKY posCntl
  8185. æFc Controls.h
  8186. æT #define
  8187. æD #define posCntl 5
  8188. æC 
  8189.  
  8190. æKY thumbCntl
  8191. æFc Controls.h
  8192. æT #define
  8193. æD #define thumbCntl 6
  8194. æC 
  8195.  
  8196. æKY dragCntl
  8197. æFc Controls.h
  8198. æT #define
  8199. æD #define dragCntl 7
  8200. æC 
  8201.  
  8202. æKY autoTrack
  8203. æFc Controls.h
  8204. æT #define
  8205. æD #define autoTrack 8
  8206. æC 
  8207.  
  8208. æKY cFrameColor
  8209. æFc Controls.h
  8210. æT #define
  8211. æD #define cFrameColor 0
  8212. æC 
  8213.  
  8214. æKY cBodyColor
  8215. æFc Controls.h
  8216. æT #define
  8217. æD #define cBodyColor 1
  8218. æC 
  8219.  
  8220. æKY cTextColor
  8221. æFc Controls.h
  8222. æT #define
  8223. æD #define cTextColor 2
  8224. æC 
  8225.  
  8226. æKY cThumbColor
  8227. æFc Controls.h
  8228. æT #define
  8229. æD #define cThumbColor 3
  8230. æC 
  8231.  
  8232. æKY calcCntlRgn
  8233. æFc Controls.h
  8234. æT #define
  8235. æD #define calcCntlRgn 10
  8236. æC 
  8237.  
  8238. æKY calcThumbRgn
  8239. æFc Controls.h
  8240. æT #define
  8241. æD #define calcThumbRgn 11
  8242. æC 
  8243.  
  8244. æKY ControlRecord
  8245. ControlPtr
  8246. ControlHandle
  8247. æFc Controls.h
  8248. æT struct
  8249. æD struct ControlRecord {
  8250.     struct ControlRecord **nextControl;
  8251.     WindowPtr contrlOwner;
  8252.     Rect contrlRect;
  8253.     unsigned char contrlVis;
  8254.     unsigned char contrlHilite;
  8255.     short contrlValue;
  8256.     short contrlMin;
  8257.     short contrlMax;
  8258.     Handle contrlDefProc;
  8259.     Handle contrlData;
  8260.     ProcPtr contrlAction;
  8261.     long contrlRfCon;
  8262.     Str255 contrlTitle;
  8263. };
  8264.  
  8265. typedef struct ControlRecord ControlRecord;
  8266. typedef ControlRecord *ControlPtr, **ControlHandle;
  8267.  
  8268. æC 
  8269. Every control is represented internally by a control record containing all pertinent
  8270. information about that control. The control record contains the following:
  8271.  
  8272.   •  A pointer to the window the control belongs to.
  8273.   •  A handle to the next control in the window’s control list.
  8274.   •  A handle to the control definition function.
  8275.   •  The control’s title, if any.
  8276.   •  A rectangle that completely encloses the control, which determines
  8277.      the control’s size and location within its window. The entire control,
  8278.      including the title of a check box or radio button, is drawn inside
  8279.      this rectangle.
  8280.   •  An indication of whether the control is currently active and how it’s
  8281.      to be highlighted.
  8282.   •  The current setting of the control (if this type of control retains a
  8283.      setting) and the minimum and maximum values the setting can assume. For
  8284.      check boxes and radio buttons, a setting of 0 means the control is off
  8285.      and 1 means it’s on.
  8286.  
  8287. The control record also contains an indication of whether the control is currently
  8288. visible or invisible. These terms refer only to whether the control is drawn in its
  8289. window, not to whether you can see it on the screen. A control may be “visible” and
  8290. still not appear on the screen, because it’s obscured by overlapping windows or other
  8291. objects.
  8292.  
  8293. There’s a field in the control record for a pointer to the control’s default action
  8294. procedure. An action procedure defines some action to be performed repeatedly for as
  8295. long as the user holds down the mouse button inside the control. The default action
  8296. procedure may be used by the Control Manager function TrackControl if you call it
  8297. without passing a pointer to an action procedure; this is discussed in detail in the
  8298. description of TrackControl in the “Control Manager Routines” section.
  8299.  
  8300. Finally, the control record includes a 32-bit reference value field, which is reserved
  8301. for use by your application. You specify an initial reference value when you create a
  8302. control, and can then read or change the reference value whenever you wish.
  8303.  
  8304. The data type for a control record is called ControlRecord. A control record is
  8305. referred to by a handle:
  8306.  
  8307. TYPE  ControlPtr     = ^ControlRecord;
  8308.       ControlHandle  = ^ControlPtr;
  8309.  
  8310. The Control Manager functions for creating a control return a handle to a newly
  8311. allocated control record; thereafter, your program should normally refer to the
  8312. control by this handle. Most of the Control Manager routines expect a control handle
  8313. as their first parameter.
  8314.  
  8315. You can store into and access most of a control record’s fields with Control Manager
  8316. routines, so normally you don’t have to know the exact field names. However, if you
  8317. want more information about the exact structure of a control record—if you’re defining
  8318. your own control types, for instance—it’s given below.
  8319.  
  8320. _______________________________________________________________________________
  8321.  
  8322. »The ControlRecord Data Type
  8323.  
  8324. The ControlRecord data type is defined as follows:
  8325.  
  8326. TYPE ControlRecord =
  8327.       PACKED RECORD
  8328.         nextControl:    ControlHandle;  {next control}
  8329.         contrlOwner:    WindowPtr;      {control's window}
  8330.         contrlRect:     Rect;           {enclosing rectangle}
  8331.         contrlVis:      Byte;           {255 if visible}
  8332.         contrlHilite:   Byte;           {highlight state}
  8333.         contrlValue:    INTEGER;        {control's current setting}
  8334.         contrlMin:      INTEGER;        {control's minimum setting}
  8335.         contrlMax:      INTEGER;        {control's maximum setting}
  8336.         contrlDefProc:  Handle;         {control definition function}
  8337.         contrlData:     Handle;         {data used by contrlDefProc}
  8338.         contrlAction:   ProcPtr;        {default action procedure}
  8339.         contrlRfCon:    LONGINT;        {control's reference value}
  8340.         contrlTitle:    Str255          {control's title}
  8341.       END;
  8342.  
  8343. NextControl is a handle to the next control associated with this control’s window.
  8344. All the controls belonging to a given window are kept in a linked list, beginning in
  8345. the controlList field of the window record and chained together through the nextControl
  8346. fields of the individual control records. The end of the list is marked by a NIL
  8347. value; as new controls are created, they’re added to the beginning of the list.
  8348.  
  8349. ContrlOwner is a pointer to the window that this control belongs to.
  8350.  
  8351. ContrlRect is the rectangle that completely encloses the control, in the local coordinates
  8352. of the control’s window.
  8353.  
  8354. When contrlVis is 0, the control is currently invisible; when it’s 255, the control
  8355. is visible.
  8356.  
  8357. ContrlHilite specifies whether and how the control is to be highlighted, indicating
  8358. whether it’s active or inactive. The HiliteControl procedure lets you set this field;
  8359. see the description of HiliteControl for more information about the meaning of the
  8360. field’s value.
  8361.  
  8362. ContrlValue is the control’s current setting. For check boxes and radio buttons, 0
  8363. means the control is off and 1 means it’s on. For dials, the fields contrlMin and
  8364. contrlMax define the range of possible settings; contrlValue may take on any value
  8365. within that range. Other (custom) control types can use these three fields as they
  8366. see fit.
  8367.  
  8368. ContrlDefProc is a handle to the control definition function for this type of control.
  8369. When you create a control, you identify its type with a control definition ID, which
  8370. is converted into a handle to the control definition function and stored in the
  8371. contrlDefProc field. Thereafter, the Control Manager uses this handle to access the
  8372. definition function; you should never need to refer to this field directly.
  8373.  
  8374. Note:  When not running in 32-bit mode, the high-order byte of the
  8375.        contrlDefProc field contains some additional information that
  8376.        the Control Manager gets from the control definition ID; for
  8377.        details, see the section “Defining Your Own Controls”.
  8378.  
  8379. ContrlData is reserved for use by the control definition function, typically to hold
  8380. additional information specific to a particular control type. For example, the standard
  8381. definition function for scroll bars uses this field for a handle to the region containing
  8382. the scroll bar’s thumb. If no more than four bytes of additional information are
  8383. needed, the definition function can store the information directly in the contrlData
  8384. field rather than use a handle.
  8385.  
  8386. ContrlAction is a pointer to the control’s default action procedure, if any. The
  8387. Control Manager function TrackControl may call this procedure to respond to the
  8388. user’s dragging the mouse inside the control.
  8389.  
  8390. ContrlRfCon is the control’s reference value field, which the application may store
  8391. into and access for any purpose.
  8392.  
  8393. ContrlTitle is the control’s title, if any.
  8394.  
  8395. æKY CtlCTab
  8396. CCTabPtr
  8397. CCTabHandle
  8398. æFc Controls.h
  8399. æT struct
  8400. æD struct CtlCTab {
  8401.     long ccSeed; /*reserved*/
  8402.     short ccRider; /*see what you have done - reserved*/
  8403.     short ctSize; /*usually 3 for controls*/
  8404.     ColorSpec ctTable[4];
  8405. };
  8406.  
  8407. typedef struct CtlCTab CtlCTab;
  8408. typedef CtlCTab *CCTabPtr, **CCTabHandle;
  8409.  
  8410. æC 
  8411. The contents and meaning of a control’s color table are determined by its control
  8412. definition function (see “The Control Color Table Resource” section). The CTabHandle
  8413. parameter used in the Color Control Manager routines provides a handle to the control
  8414. color table. The components of a control color table are defined as follows:
  8415.  
  8416. TYPE
  8417.   CCTabHandle = ^CCTabPtr;
  8418.   CCTabPtr    = ^CtlCTab;
  8419.   CtlCTab     = RECORD
  8420.                   ccSeed:      LONGINT;    {not used for controls}
  8421.                   ccRider:     INTEGER;    {not used for controls}
  8422.                   ctSize:      INTEGER;    {number of entries in table –1}
  8423.                   ctTable:     cSpecArray  {array of ColorSpec records}
  8424.                 END;
  8425.  
  8426. Field descriptions
  8427.  
  8428. ccSeed        The ccSeed field is unused in control color tables.
  8429.  
  8430. ccRider       The ccRider field is unused in control color tables.
  8431.  
  8432. ctSize        The ctSize field defines the number of elements in the table,
  8433.               minus one. For controls drawn with the standard definition
  8434.               procedure, this field is always 3.
  8435.  
  8436. ctTable       The ctTable field holds an array of colorSpec records. Each
  8437.               colorSpec is made up of a partIdentifier field and a partRGB
  8438.               field. The partIdentifier field holds an integer which
  8439.               associates an RGBColor to a particular part of the control.
  8440.               The definition procedures attempt to find the appropriate part
  8441.               identifier when preparing to draw a part. If that part
  8442.               identifier is not found, the first color in the table is
  8443.               used to draw the part. The part identifiers can appear in any
  8444.               order in the table. The partRGB field specifies a standard RGB
  8445.               color record, indicating what absolute color will be used to
  8446.               draw the control part found in the partIdentifier field.
  8447.  
  8448. A standard control color table is shown in Figure 6.
  8449.  
  8450. •••Refer to Figure 6.•••
  8451.  
  8452. Figure 6–Control Color Table
  8453.  
  8454. The 'cctb' resource is an exact image of this control table data structure, and is
  8455. stored in the same format as 'clut' color table resources.
  8456.  
  8457. Standard buttons, check boxes, and radio buttons use a four-element color table with
  8458. part identifiers as shown below:
  8459.  
  8460.   cFrameColor (0)       Frame color
  8461.   cBodyColor (1)        Fill color for body of control
  8462.   cTextColor (2)        Text color
  8463.   cThumbColor (3)       Unused
  8464.  
  8465. When highlighted, plain buttons exchange their body and text colors (colors 1 and 2);
  8466. check boxes and radio buttons change their appearance without changing colors.  All
  8467. three types indicate deactivation by dimming their text with no change in colors.
  8468.  
  8469. Standard scroll bars use a four-element color table with part identifiers as shown
  8470. below:
  8471.  
  8472.   cFrameColor (0)       Frame color, foreground color for shaft and arrows
  8473.   cBodyColor (1         Background color for shaft and arrows
  8474.   cTextColor (2)        Unused
  8475.   cThumbColor (3)       Fill color for thumb
  8476.  
  8477. When highlighted, the arrows are filled with the foreground color (color 0) within
  8478. the arrow outline. A deactivated scroll bar shows no indicator, and displays its
  8479. shaft in solid background color (color 1), with no pattern.
  8480.  
  8481. The 'cctb' resource = 0 is read into the application heap when the application starts,
  8482. and serves as the default control color table. The last record in the auxiliary
  8483. control list points to the default 'cctb' resource. When drawing a control, the
  8484. standard control definition function searches the list for an auxiliary control
  8485. record whose acOwner points to the control being drawn.  If it finds such a record,
  8486. it uses the color table designated by that record; if it doesn’t find one before
  8487. reaching the default record at the end of the list, it uses the default color table
  8488. instead. All types of controls share the same default record. The default auxiliary
  8489. control record is recognized by NIL values in both its acNext and acOwner fields; the
  8490. application must not change these fields.
  8491.  
  8492. A nonstandard control definition function can use color tables of any desired size
  8493. and define their contents in any way it wishes, except that part indices 1 to 127 are
  8494. reserved for system definition.  Any such nonstandard function should take care to
  8495. bypass the defaulting mechanism just described, by allocating an explicit auxiliary
  8496. record for every control it creates.
  8497.  
  8498. æKY AuxCtlRec
  8499. AuxCtlPtr
  8500. AuxCtlHandle
  8501. æFc Controls.h
  8502. æT struct
  8503. æD struct AuxCtlRec {
  8504.     Handle acNext; /*handle to next AuxCtlRec*/
  8505.     ControlHandle acOwner; /*handle for aux record's control*/
  8506.     CCTabHandle acCTable; /*color table for this control*/
  8507.     short acFlags; /*misc flag byte*/
  8508.     long acReserved; /*reserved for use by Apple*/
  8509.     long acRefCon; /*for use by application*/
  8510. };
  8511.  
  8512. typedef struct AuxCtlRec AuxCtlRec;
  8513. typedef AuxCtlRec *AuxCtlPtr, **AuxCtlHandle;
  8514.  
  8515. æC 
  8516. The information needed for drawing controls in color is kept in a linked list of
  8517. auxiliary control records, beginning in the global variable AuxCtlHead.
  8518. (Notice that there is just one global list for all controls in all windows, not a
  8519. separate one for each window.) Each window record has a handle to the list of controls.
  8520. Figure 5 shows the auxiliary control list structure.
  8521.  
  8522. •••Refer to Figure 5.•••
  8523.  
  8524. Figure 5–Auxiliary Control List
  8525.  
  8526. Each auxiliary control record is a relocatable object residing in the application
  8527. heap. The most important information it holds is a handle to the control’s individual
  8528. color table (see the “Control Color Tables” section).  The rest of the record consists
  8529. of a link to the next record in the list, a field that identifies the control’s
  8530. owner, a 4-byte field reserved for future expansion, and a 4-byte reference constant
  8531. for use by the application:
  8532.  
  8533. TYPE
  8534.   AuxCtlHandle = ^AuxCtlPtr;
  8535.   AuxCtlPtr    = ^AuxCtlRec;
  8536.   AuxCtlRec    = RECORD
  8537.                    acNext:      AuxCtlHandle;   {handle to next record in list}
  8538.                    acOwner:     ControlHandle;  {handle to owning control}
  8539.                    acCTable:    CCTabHandle;    {handle to control's color }
  8540.                                                 { table}
  8541.                    acFlags:     INTEGER;        {miscellaneous flags; reserved}
  8542.                    acReserved:  LONGINT;        {reserved for future expansion}
  8543.                    acRefCon:    LONGINT         {reserved for application use}
  8544.                  END;
  8545.  
  8546. Field descriptions
  8547.  
  8548. acNext        The acNext field contains a handle to the next record in
  8549.               the auxiliary control list.
  8550.  
  8551. acOwner       The acOwner field contains the handle of the control to
  8552.               which this auxiliary record belongs. Used as an ID field.
  8553.  
  8554. acCTable      The acCTable contains the handle to the control’s color
  8555.               table (see “Control Color Tables” below).
  8556.  
  8557. acFlags       The acFlags field contains miscellaneous flags for use by
  8558.               the Control Manager; this field is reserved.
  8559.  
  8560. acReserved    The acReserved field is reserved for future expansion;
  8561.               this must be set to 0 for future compatibility.
  8562.  
  8563. acRefCon      The acRefCon field is a reference constant for use by
  8564.               the application.
  8565.  
  8566. Not every control needs an auxiliary control record.  When an application is started,
  8567. a resource containing a default color table is loaded from the system resource file;
  8568. this resource defines a standard set of control colors. Since there is no InitControls
  8569. routine, this happens when an application calls InitWindows.
  8570.  
  8571. Separate auxiliary control records are needed only for controls whose color usage
  8572. differs from the default.  Each such nonstandard control must have its own auxiliary
  8573. record, even if it uses the same colors as another control. This allows two or more
  8574. auxiliary records to share the same control color table. If the control color table
  8575. is a resource, it won’t be deleted by DisposeControl. When using an auxiliary record
  8576. that is not stored as a resource, the application should not deallocate the color
  8577. table if another control is still using it.
  8578.  
  8579. A control created from scratch will initially have no auxiliary control record.  If
  8580. it is to use nonstandard colors, it must be given an auxiliary record and a color
  8581. table with SetCtlColor (see the “Control Manager Routines” section).  Such a control
  8582. should normally be made invisible at creation and then displayed with ShowControl
  8583. after the colors are set.  For controls created from a 'CNTL' resource,  the color
  8584. table can be specified as a resource as well. See the section titled “The Control
  8585. Color Table Resource”.
  8586.  
  8587. A/UX systems:  When using 32-bit mode. every control has its own auxiliary
  8588.                record. If there is no specific set of control colors for
  8589.                this control, the acCTable will point to the default color table.
  8590.  
  8591. æKY NewControl
  8592. æFc Controls.h
  8593. æT Function
  8594. æTN A954
  8595. æD pascal ControlHandle NewControl(WindowPtr theWindow,const Rect *boundsRect,
  8596.     const Str255 title,Boolean visible,short value,short min,short max,short procID,
  8597.     long refCon)
  8598.     = 0xA954; 
  8599. æDT ControlHandle myVariable = NewControl((WindowPtr) theWindow,(const Rect *) boundsRect,(
  8600.     const) Str255 title,(Boolean) visible,(short) value,(short) min,(short) max,(short) procID,()
  8601.     long refCon);
  8602. æMM
  8603. æRI I-319, P-112, 114, 177
  8604. æC  
  8605. NewControl creates a control, adds it to the beginning of theWindow’s control list,
  8606. and returns a handle to the new control. The values passed as parameters are stored
  8607. in the corresponding fields of the control record, as described below. The field that
  8608. determines highlighting is set to 0 (no highlighting) and the pointer to the default
  8609. action procedure is set to NIL (none).
  8610.  
  8611. Note:  The control definition function may do additional initialization,
  8612.        including changing any of the fields of the control record. The only
  8613.        standard control for which additional initialization is done is the
  8614.        scroll bar; its control definition function allocates space for a
  8615.        region to hold the thumb and stores the region handle in the
  8616.        contrlData field of the control record.
  8617.  
  8618. TheWindow is the window the new control will belong to. All coordinates pertaining to
  8619. the control will be interpreted in this window’s local coordinate system.
  8620.  
  8621. BoundsRect, given in theWindow’s local coordinates, is the rectangle that encloses
  8622. the control and thus determines its size and location. Note the following about the
  8623. enclosing rectangle for the standard controls:
  8624.  
  8625.   •  Simple buttons are drawn to fit the rectangle exactly. (The control
  8626.      definition function calls the QuickDraw procedure FrameRoundRect.) To
  8627.      allow for the tallest characters in the system font, there should be
  8628.      at least a 20-point difference between the top and bottom coordinates
  8629.      of the rectangle.
  8630.   •  For check boxes and radio buttons, there should be at least a 16-point
  8631.      difference between the top and bottom coordinates.
  8632.   •  By convention, scroll bars are 16 pixels wide, so there should be a
  8633.      16-point difference between the left and right (or top and bottom)
  8634.      coordinates. (If there isn’t, the scroll bar will be scaled to fit
  8635.      the rectangle.) A standard scroll bar should be at least 48 pixels
  8636.      long, to allow room for the scroll arrows and thumb.
  8637.  
  8638. Title is the control’s title, if any (if none, you can just pass the empty string as
  8639. the title). Be sure the title will fit in the control’s enclosing rectangle; if it
  8640. won’t it will be truncated on the right for check boxes and radio buttons, or centered
  8641. and truncated on both ends for simple buttons.
  8642.  
  8643. Note:  Some non-Roman systems write text from right-to-left, in which
  8644.        case radio buttons and check boxes are drawn with their titles
  8645.        on the left of the control.  They are also truncated on the left.
  8646.        See the Script Manager chapter for more information.
  8647.  
  8648. If the visible parameter is TRUE, NewControl draws the control.
  8649.  
  8650. Note:  It does not use the standard window updating mechanism, but
  8651.        instead draws the control immediately in the window.
  8652.  
  8653. The min and max parameters define the control’s range of possible settings; the value
  8654. parameter gives the initial setting. For controls that don’t retain a setting, such
  8655. as buttons, the values you supply for these parameters will be stored in the control
  8656. record but will never be used. So it doesn’t matter what values you give for those
  8657. controls—0 for all three parameters will do. For controls that just retain an on-or-off
  8658. setting, such as check boxes or radio buttons, min should be 0 (meaning the control
  8659. is off) and max should be 1
  8660. (meaning it’s on). For dials, you can specify whatever values are appropriate for
  8661. min, max, and value.
  8662.  
  8663. ProcID is the control definition ID, which leads to the control definition function
  8664. for this type of control. (The function is read into memory if it
  8665. isn’t already in memory.) The control definition IDs for the standard control types
  8666. are listed above under “Controls and Resources”. Control definition IDs for custom
  8667. control types are discussed later under “Defining Your Own Controls”.
  8668.  
  8669. RefCon is the control’s reference value, set and used only by your application.
  8670.  
  8671. æKY SetCTitle
  8672. æFc Controls.h
  8673. æT Function
  8674. æTN A95F
  8675. æD pascal void SetCTitle(ControlHandle theControl,const Str255 title)
  8676.     = 0xA95F; 
  8677. æDT SetCTitle((ControlHandle) theControl,(const Str255) title);
  8678. æMM
  8679. æRI I-321
  8680. æC  
  8681. SetCTitle sets theControl’s title to the given string and redraws the control.
  8682.  
  8683. æKY GetCTitle
  8684. æFc Controls.h
  8685. æT Function
  8686. æTN A95E
  8687. æD pascal void GetCTitle(ControlHandle theControl,Str255 title)
  8688.     = 0xA95E; 
  8689. æDT GetCTitle((ControlHandle) theControl,(Str255) title);
  8690. æRI I-321
  8691. æC 
  8692. GetCTitle returns theControl’s title as the value of the title parameter.
  8693.  
  8694. æKY GetNewControl
  8695. æFc Controls.h
  8696. æT Function
  8697. æTN A9BE
  8698. æD pascal ControlHandle GetNewControl(short controlID,WindowPtr owner)
  8699.     = 0xA9BE; 
  8700. æDT ControlHandle myVariable = GetNewControl((short) controlID,(WindowPtr) owner);
  8701. æMM
  8702. æRT 203
  8703. æRI I-321, P-112, 113, 114, 172
  8704. æC 
  8705. GetNewControl creates a control from a control template stored in a resource file,
  8706. adds it to the beginning of theWindow’s control list, and returns a handle to the new
  8707. control. ControlID is the resource ID of the template. GetNewControl works exactly
  8708. the same as NewControl (above), except that it gets the initial values for the new
  8709. control’s fields from the specified control template instead of accepting them as
  8710. parameters. If the control template can’t be read from the resource file, GetNewControl
  8711. returns NIL. It releases the memory occupied by the resource before returning.
  8712.  
  8713. The system default control colors are stored in the System file and ROMResources as
  8714. 'cctb' resource = 0. By including a 'cctb' resource = 0 in your application, it is
  8715. possible to change the default colors that will be used for all controls, unless a
  8716. specific 'cctb' exists for a control defined within the application.
  8717.  
  8718. When you use GetNewControl for the control resource 'CNTL', GetNewControl will attempt
  8719. to load a 'cctb' resource with the same ID as the 'CNTL' resource ID, if one is
  8720. present. It then executes the SetCtlColor call.
  8721.  
  8722. The following part identifiers for control elements should be present in the ColorSpec.value
  8723. field:
  8724.  
  8725.   cFrameColor (0)       Frame color
  8726.   cBodyColor (1)        Fill color for body of control
  8727.   cTextColor (2)        Text color
  8728.   cThumbColor (3)       Thumb color
  8729.  
  8730. These identifiers may be present in any order; for instance, the text or indicator
  8731. color values may be stored before the fill and frame colors in the ColorSpec record
  8732. structure. If a part identifier is not found, then the first color in the color table
  8733. will be used.
  8734.  
  8735. æKY DisposeControl
  8736. æFc Controls.h
  8737. æT Function
  8738. æTN A955
  8739. æD pascal void DisposeControl(ControlHandle theControl)
  8740.     = 0xA955; 
  8741. æDT DisposeControl((ControlHandle) theControl);
  8742. æMM
  8743. æRI I-321, P-168
  8744. æC 
  8745. Assembly-language note:  The macro you invoke to call DisposeControl from
  8746.                          assembly language is named _DisposControl.
  8747.  
  8748. DisposeControl removes theControl from the screen, deletes it from its window’s
  8749. control list, and releases the memory occupied by the control record and any data
  8750. structures associated with the control.
  8751.  
  8752. æKY KillControls
  8753. æFc Controls.h
  8754. æT Function
  8755. æTN A956
  8756. æD pascal void KillControls(WindowPtr theWindow)
  8757.     = 0xA956; 
  8758. æDT KillControls((WindowPtr) theWindow);
  8759. æMM
  8760. æRI I-321, P-113, 175
  8761. æC 
  8762. KillControls disposes of all controls associated with theWindow by calling DisposeControl
  8763. (above) for each.
  8764.  
  8765. Note:  Remember that the Window Manager procedures CloseWindow and
  8766.        DisposeWindow automatically dispose of all controls associated
  8767.        with the given window.
  8768.  
  8769. æKY HideControl
  8770. æFc Controls.h
  8771. æT Function
  8772. æTN A958
  8773. æD pascal void HideControl(ControlHandle theControl)
  8774.     = 0xA958; 
  8775. æDT HideControl((ControlHandle) theControl);
  8776. æMM
  8777. æRI I-322, P-113, 114, 174
  8778. æC 
  8779. HideControl makes theControl invisible. It fills the region the control occupies
  8780. within its window with the background pattern of the window’s grafPort. It also adds
  8781. the control’s enclosing rectangle to the window’s update region, so that anything
  8782. else that was previously obscured by the control will reappear on the screen. If the
  8783. control is already invisible, HideControl has no effect.
  8784.  
  8785. æKY ShowControl
  8786. æFc Controls.h
  8787. æT Function
  8788. æTN A957
  8789. æD pascal void ShowControl(ControlHandle theControl)
  8790.     = 0xA957; 
  8791. æDT ShowControl((ControlHandle) theControl);
  8792. æMM
  8793. æRT 197
  8794. æRI I-322, P-113, 114, 181
  8795. æC 
  8796. ShowControl makes theControl visible. The control is drawn in its window but may be
  8797. completely or partially obscured by overlapping windows or other objects. If the
  8798. control is already visible, ShowControl has no effect.
  8799.  
  8800. æKY DrawControls
  8801. æFc Controls.h
  8802. æT Function
  8803. æTN A969
  8804. æD pascal void DrawControls(WindowPtr theWindow)
  8805.     = 0xA969; 
  8806. æDT DrawControls((WindowPtr) theWindow);
  8807. æRT 203
  8808. æRI I-322, P-169
  8809. æC 
  8810. DrawControls draws all controls currently visible in theWindow. The controls are
  8811. drawn in reverse order of creation; thus in case of overlap the earliest-created
  8812. controls appear frontmost in the window.
  8813.  
  8814. Note:  Window Manager routines such as SelectWindow, ShowWindow, and
  8815.        BringToFront do not automatically call DrawControls to display
  8816.        the window’s controls. They just add the appropriate regions to
  8817.        the window’s update region, generating an update event. Your program
  8818.        should always call DrawControls explicitly upon receiving an update
  8819.        event for a window that contains controls.
  8820.  
  8821. æKY Draw1Control
  8822. æFc Controls.h
  8823. æT Function
  8824. æTN A96D
  8825. æD pascal void Draw1Control(ControlHandle theControl)
  8826.     = 0xA96D; 
  8827. æDT Draw1Control((ControlHandle) theControl);
  8828. æMM
  8829. æRI IV-53
  8830. æC 
  8831. [128K ROM]
  8832.  
  8833. Draw1Control draws the specified control if it’s visible within the window.
  8834.  
  8835. æKY HiliteControl
  8836. æFc Controls.h
  8837. æT Function
  8838. æTN A95D
  8839. æD pascal void HiliteControl(ControlHandle theControl,short hiliteState)
  8840.     = 0xA95D; 
  8841. æDT HiliteControl((ControlHandle) theControl,(short) hiliteState);
  8842. æMM
  8843. æRI I-322
  8844. æC 
  8845. HiliteControl changes the way theControl is highlighted. HiliteState has one of the
  8846. following values:
  8847.  
  8848.   •  The value 0 means no highlighting. (The control is active.)
  8849.   •  A value between 1 and 253 is interpreted as a part code designating
  8850.      the part of the (active) control to be highlighted.
  8851.   •  The value 255 means that the control is to be made inactive and
  8852.      highlighted accordingly.
  8853.  
  8854. Note:  The value 254 should not be used; this value is reserved for future use.
  8855.  
  8856. HiliteControl calls the control definition function to redraw the control with its
  8857. new highlighting.
  8858.  
  8859. æKY UpdtControl
  8860. æFc Controls.h
  8861. æT Function
  8862. æTN A953
  8863. æD pascal void UpdtControl(WindowPtr theWindow,RgnHandle updateRgn)
  8864.     = 0xA953; 
  8865. æDT UpdtControl((WindowPtr) theWindow,(RgnHandle) updateRgn);
  8866. æMM
  8867. æRI IV-53
  8868. æC  
  8869. [128K ROM]
  8870.  
  8871. UpdtControl is a faster version of the DrawControls procedure. Instead of drawing all
  8872. of the controls in theWindow, UpdtControl draws only the controls that are in the
  8873. specified update region. UpdtControl is called in response to an update event, and is
  8874. usually bracketed by calls to the Window Manager procedures BeginUpdate and EndUpdate.
  8875. UpdateRgn should be set to the visRgn of theWindow’s port (for more details, see the
  8876. BeginUpdate procedure in the Window Manager chapter).
  8877.  
  8878. Note:  In general, controls are in a dialog box and are automatically
  8879.        drawn by the DrawDialog procedure.
  8880.  
  8881. æKY MoveControl
  8882. æFc Controls.h
  8883. æT Function
  8884. æTN A959
  8885. æD pascal void MoveControl(ControlHandle theControl,short h,short v)
  8886.     = 0xA959; 
  8887. æDT MoveControl((ControlHandle) theControl,(short) h,(short) v);
  8888. æMM
  8889. æRI I-325, P-113, 176
  8890. æC 
  8891. MoveControl moves theControl to a new location within its window. The top left corner
  8892. of the control’s enclosing rectangle is moved to the horizontal and vertical coordinates
  8893. h and v (given in the local coordinates of the control’s window); the bottom right
  8894. corner is adjusted accordingly, to keep the size of the rectangle the same as before.
  8895. If the control is currently visible, it’s hidden and then redrawn at its new location.
  8896.  
  8897. æKY SizeControl
  8898. æFc Controls.h
  8899. æT Function
  8900. æTN A95C
  8901. æD pascal void SizeControl(ControlHandle theControl,short w,short h)
  8902.     = 0xA95C; 
  8903. æDT SizeControl((ControlHandle) theControl,(short) w,(short) h);
  8904. æMM
  8905. æRI I-326, P-113, 181
  8906. æC 
  8907. SizeControl changes the size of theControl’s enclosing rectangle. The bottom right
  8908. corner of the rectangle is adjusted to set the rectangle’s width and height to the
  8909. number of pixels specified by w and h; the position of the top left corner is not
  8910. changed. If the control is currently visible, it’s hidden and then redrawn in its new
  8911. size.
  8912.  
  8913. æKY SetCtlValue
  8914. æFc Controls.h
  8915. æT Function
  8916. æTN A963
  8917. æD pascal void SetCtlValue(ControlHandle theControl,short theValue)
  8918.     = 0xA963; 
  8919. æDT SetCtlValue((ControlHandle) theControl,(short) theValue);
  8920. æMM
  8921. æRT 197
  8922. æRI I-326
  8923. æC 
  8924. SetCtlValue sets theControl’s current setting to theValue and redraws the control to
  8925. reflect the new setting. For check boxes and radio buttons, the value 1 fills the
  8926. control with the appropriate mark, and 0 clears it. For scroll bars, SetCtlValue
  8927. redraws the thumb where appropriate.
  8928.  
  8929. If the specified value is out of range, it’s forced to the nearest endpoint of the
  8930. current range (that is, if theValue is less than the minimum setting, SetCtlValue
  8931. sets the current setting to the minimum; if theValue is greater than the maximum
  8932. setting, it sets the current setting to the maximum).
  8933.  
  8934. æKY GetCtlValue
  8935. æFc Controls.h
  8936. æT Function
  8937. æTN A960
  8938. æD pascal short GetCtlValue(ControlHandle theControl)
  8939.     = 0xA960; 
  8940. æDT short myVariable = GetCtlValue((ControlHandle) theControl);
  8941. æRI I-326, P-114, 171
  8942. æC 
  8943. GetCtlValue returns theControl’s current setting.
  8944.  
  8945. æKY SetCtlMin
  8946. æFc Controls.h
  8947. æT Function
  8948. æTN A964
  8949. æD pascal void SetCtlMin(ControlHandle theControl,short minValue)
  8950.     = 0xA964; 
  8951. æDT SetCtlMin((ControlHandle) theControl,(short) minValue);
  8952. æMM
  8953. æRI I-326
  8954. æC 
  8955. Assembly-language note:  The macro you invoke to call SetCtlMin from
  8956.                          assembly language is named _SetMinCtl.
  8957.  
  8958. SetCtlMin sets theControl’s minimum setting to minValue and redraws the control to
  8959. reflect the new range. If the control’s current setting is less than minValue, the
  8960. setting is changed to the new minimum.
  8961.  
  8962. æKY GetCtlMin
  8963. æFc Controls.h
  8964. æT Function
  8965. æTN A961
  8966. æD pascal short GetCtlMin(ControlHandle theControl)
  8967.     = 0xA961; 
  8968. æDT short myVariable = GetCtlMin((ControlHandle) theControl);
  8969. æRI I-327
  8970. æC  
  8971. Assembly-language note:  The macro you invoke to call GetCtlMin from
  8972.                          assembly language is named _GetMinCtl.
  8973.  
  8974. GetCtlMin returns theControl’s minimum setting.
  8975.  
  8976. æKY SetCtlMax
  8977. æFc Controls.h
  8978. æT Function
  8979. æTN A965
  8980. æD pascal void SetCtlMax(ControlHandle theControl,short maxValue)
  8981.     = 0xA965; 
  8982. æDT SetCtlMax((ControlHandle) theControl,(short) maxValue);
  8983. æMM
  8984. æRI I-327
  8985. æC 
  8986. Assembly-language note:  The macro you invoke to call SetCtlMax from
  8987.                          assembly language is named _SetMaxCtl.
  8988.  
  8989. SetCtlMax sets theControl’s maximum setting to maxValue and redraws the control to
  8990. reflect the new range. If the control’s current setting is greater than maxValue, the
  8991. setting is changed to the new maximum.
  8992.  
  8993. Note:  If you set the maximum setting of a scroll bar equal to its minimum
  8994.        setting, the control definition function will make the scroll bar
  8995.        inactive.
  8996.  
  8997. æKY GetCtlMax
  8998. æFc Controls.h
  8999. æT Function
  9000. æTN A962
  9001. æD pascal short GetCtlMax(ControlHandle theControl)
  9002.     = 0xA962; 
  9003. æDT short myVariable = GetCtlMax((ControlHandle) theControl);
  9004. æRI I-327
  9005. æC 
  9006. Assembly-language note:  The macro you invoke to call GetCtlMax from
  9007.                          assembly language is named _GetMaxCtl.
  9008.  
  9009. GetCtlMax returns theControl’s maximum setting.
  9010.  
  9011. æKY SetCRefCon
  9012. æFc Controls.h
  9013. æT Function
  9014. æTN A95B
  9015. æD pascal void SetCRefCon(ControlHandle theControl,long data)
  9016.     = 0xA95B; 
  9017. æDT SetCRefCon((ControlHandle) theControl,(long) data);
  9018. æRI I-327
  9019. æC 
  9020. SetCRefCon sets theControl’s reference value to the given data.
  9021.  
  9022. æKY GetCRefCon
  9023. æFc Controls.h
  9024. æT Function
  9025. æTN A95A
  9026. æD pascal long GetCRefCon(ControlHandle theControl)
  9027.     = 0xA95A; 
  9028. æDT long myVariable = GetCRefCon((ControlHandle) theControl);
  9029. æRI I-327
  9030. æC 
  9031. GetCRefCon returns theControl’s current reference value.
  9032.  
  9033. æKY SetCtlAction
  9034. æFc Controls.h
  9035. æT Function
  9036. æTN A96B
  9037. æD pascal void SetCtlAction(ControlHandle theControl,ProcPtr actionProc)
  9038.     = 0xA96B; 
  9039. æDT SetCtlAction((ControlHandle) theControl,(ProcPtr) actionProc);
  9040. æRI I-328
  9041. æC 
  9042. SetCtlAction sets theControl’s default action procedure to actionProc.
  9043.  
  9044. æKY GetCtlAction
  9045. æFc Controls.h
  9046. æT Function
  9047. æTN A96A
  9048. æD pascal ProcPtr GetCtlAction(ControlHandle theControl)
  9049.     = 0xA96A; 
  9050. æDT ProcPtr myVariable = GetCtlAction((ControlHandle) theControl);
  9051. æRI I-328, IV-53
  9052. æC  
  9053. GetCtlAction returns a pointer to theControl’s default action procedure, if any. (It
  9054. returns whatever is in that field of the control record.)
  9055.  
  9056. æKY DragControl
  9057. æFc Controls.h
  9058. æT Function
  9059. æTN A967
  9060. æD pascal void DragControl(ControlHandle theControl,Point startPt,const Rect *limitRect,
  9061.     const Rect *slopRect,short axis)
  9062.     = 0xA967; 
  9063. æDT DragControl((ControlHandle) theControl,(Point) startPt,(const Rect *) limitRect,(
  9064.     const Rect) * slopRect,(short) axis);
  9065. æMM
  9066. æRI I-325
  9067. æC 
  9068. Called with the mouse button down inside theControl, DragControl pulls a dotted
  9069. outline of the control around the screen, following the movements of the mouse until
  9070. the button is released. When the mouse button is released, DragControl calls MoveControl
  9071. to move the control to the location to which it was dragged.
  9072.  
  9073. Note:  Before beginning to follow the mouse, DragControl calls the control
  9074.        definition function to allow it to do its own “custom dragging” if
  9075.        it chooses. If the definition function doesn’t choose to do any
  9076.        custom dragging, DragControl uses the default method of dragging
  9077.        described here.
  9078.  
  9079. The startPt, limitRect, slopRect, and axis parameters have the same meaning as for
  9080. the Window Manager function DragGrayRgn. These parameters are reviewed briefly below;
  9081. see the description of DragGrayRgn in the Window Manager chapter for more details.
  9082.  
  9083.   •  StartPt is assumed to be the point where the mouse button was originally
  9084.      pressed, in the local coordinates of the control’s window.
  9085.   •  LimitRect limits the travel of the control’s outline, and should normally
  9086.      coincide with or be contained within the window’s content region.
  9087.   •  SlopRect allows the user some “slop” in moving the mouse; it should
  9088.      completely enclose limitRect.
  9089.   •  The axis parameter allows you to constrain the control’s motion to
  9090.      only one axis. It has one of the following values:
  9091.  
  9092.        CONST  noConstraint = 0;    {no constraint}
  9093.               hAxisOnly    = 1;    {horizontal axis only}
  9094.               vAxisOnly    = 2;    {vertical axis only}
  9095.  
  9096. Assembly-language note:  Like TrackControl, DragControl invokes the
  9097.                          macro _DragTheRgn, so you can use the global
  9098.                          variables DragHook and DragPattern.
  9099.  
  9100. æKY TestControl
  9101. æFc Controls.h
  9102. æT Function
  9103. æTN A966
  9104. æD pascal short TestControl(ControlHandle theControl,Point thePt)
  9105.     = 0xA966; 
  9106. æDT short myVariable = TestControl((ControlHandle) theControl,(Point) thePt);
  9107. æMM
  9108. æRI I-325
  9109. æC  
  9110. If theControl is visible and active, TestControl tests which part of the control
  9111. contains thePoint (in the local coordinates of the control’s window); it returns the
  9112. corresponding part code, or 0 if the point is outside the control. If the control is
  9113. invisible or inactive, TestControl returns 0. TestControl is called by FindControl
  9114. and TrackControl; normally you won’t need to call it yourself.
  9115.  
  9116. æKY TrackControl
  9117. æFc Controls.h
  9118. æT Function
  9119. æTN A968
  9120. æD pascal short TrackControl(ControlHandle theControl,Point thePoint,ProcPtr actionProc)
  9121.     = 0xA968; 
  9122. æDT short myVariable = TrackControl((ControlHandle) theControl,(Point) thePoint,(ProcPtr) actionProc);
  9123. æMM
  9124. æRI I-323, P-114, 184
  9125. æC 
  9126. When the mouse button is pressed in a visible, active control, the application should
  9127. call TrackControl with theControl equal to the control handle and startPt equal to
  9128. the point where the mouse button was pressed (in the local coordinates of the control’s
  9129. window). TrackControl follows the movements of the mouse and responds in whatever way
  9130. is appropriate until the mouse button is released; the exact response depends on the
  9131. type of control and the part of the control in which the mouse button was pressed. If
  9132. highlighting is appropriate, TrackControl does the highlighting, and undoes it before
  9133. returning. When the mouse button is released, TrackControl returns with the part code
  9134. if the mouse is in the same part of the control that it was originally in, or with 0
  9135. if not
  9136. (in which case the application should do nothing).
  9137.  
  9138. If the mouse button was pressed in an indicator, TrackControl drags a dotted outline
  9139. of it to follow the mouse. When the mouse button is released, TrackControl calls the
  9140. control definition function to reposition the control’s indicator. The control definition
  9141. function for scroll bars responds by redrawing the thumb, calculating the control’s
  9142. current setting based on the new relative position of the thumb, and storing the
  9143. current setting in the control record; for example, if the minimum and maximum settings
  9144. are 0 and 10, and the thumb is in the middle of the scroll bar, 5 is stored as the
  9145. current setting. The application must then scroll to the corresponding relative
  9146. position in the document.
  9147.  
  9148. TrackControl may take additional actions beyond highlighting the control or dragging
  9149. the indicator, depending on the value passed in the actionProc parameter, as described
  9150. below. The following tells you what to pass for the standard control types; for a
  9151. custom control, what you pass will depend on how the control is defined.
  9152.  
  9153.   •  If actionProc is NIL, TrackControl performs no additional actions. This
  9154.      is appropriate for simple buttons, check boxes, radio buttons, and the
  9155.      thumb of a scroll bar.
  9156.   •  ActionProc may be a pointer to an action procedure that defines some
  9157.      action to be performed repeatedly for as long as the user holds down
  9158.      the mouse button. (See below for details.)
  9159.   •  If actionProc is POINTER(–1), TrackControl looks in the control record
  9160.      for a pointer to the control’s default action procedure. If that field
  9161.      of the control record contains a procedure pointer, TrackControl uses
  9162.      the action procedure it points to; if the field contains POINTER (–1),
  9163.      TrackControl calls the control definition function to perform the
  9164.      necessary action. (If the field contains NIL, TrackControl does nothing.)
  9165.  
  9166. The action procedure in the control definition function is described in the section
  9167. “Defining Your Own Controls”. The following paragraphs describe only the action
  9168. procedure whose pointer is passed in the actionProc parameter or stored in the control
  9169. record.
  9170.  
  9171. If the mouse button was pressed in an indicator, the action procedure (if any) should
  9172. have no parameters. This procedure must allow for the fact that the mouse may not be
  9173. inside the original control part.
  9174.  
  9175. If the mouse button was pressed in a control part other than an indicator, the action
  9176. procedure should be of the form
  9177.  
  9178. PROCEDURE MyAction (theControl:  ControlHandle; partCode:  INTEGER);
  9179.  
  9180. In this case, TrackControl passes the control handle and the part code to the action
  9181. procedure. (It passes 0 in the partCode parameter if the mouse has moved outside the
  9182. original control part.) As an example of this type of action procedure, consider what
  9183. should happen when the mouse button is pressed in a scroll arrow or paging region in
  9184. a scroll bar. For these cases, your action procedure should examine the part code to
  9185. determine exactly where the mouse button was pressed, scroll up or down a line or
  9186. page as appropriate, and call SetCtlValue to change the control’s setting and redraw
  9187. the thumb.
  9188.  
  9189. Warning:  Since it has a different number of parameters depending on whether
  9190.           the mouse button was pressed in an indicator or elsewhere, the
  9191.           action procedure you pass to TrackControl (or whose pointer you
  9192.           store in the control record) can be set up for only one case or
  9193.           the other. If you store a pointer to a default action procedure
  9194.           in a control record, be sure it will be used only when appropriate
  9195.           for that type of action procedure. The only way to specify actions
  9196.           in response to all mouse-down events in a control, regardless of
  9197.           whether they’re in an indicator, is via the control definition
  9198.           function.
  9199.  
  9200. Assembly-language note:  If you store a pointer to a procedure in the global
  9201.                          variable DragHook, that procedure will be called
  9202.                          repeatedly (with no parameters) for as long as the
  9203.                          user holds down the mouse button. TrackControl
  9204.                          invokes the Window Manager macro _DragTheRgn,
  9205.                          which calls the DragHook procedure. _DragTheRgn
  9206.                          uses the pattern stored in the global variable
  9207.                          DragPattern for the dragged outline of the indicator.
  9208.  
  9209. æKY FindControl
  9210. æFc Controls.h
  9211. æT Function
  9212. æTN A96C
  9213. æD pascal short FindControl(Point thePoint,WindowPtr theWindow,ControlHandle *theControl)
  9214.     = 0xA96C; 
  9215. æDT short myVariable = FindControl((Point) thePoint,(WindowPtr) theWindow,(ControlHandle *) theControl);
  9216. æMM
  9217. æRI I-323, P-98, 114, 170
  9218. æC  
  9219. When the Window Manager function FindWindow reports that the mouse button was pressed
  9220. in the content region of a window, and the window contains controls, the application
  9221. should call FindControl with theWindow equal to the window pointer and thePoint equal
  9222. to the point where the mouse button was pressed (in the window’s local coordinates).
  9223. FindControl tells which of the window’s controls, if any, the mouse button was pressed
  9224. in:
  9225.  
  9226.   •  If it was pressed in a visible, active control, FindControl sets the
  9227.      whichControl parameter to the control handle and returns a part code
  9228.      identifying the part of the control that it was pressed in.
  9229.   •  If it was pressed in an invisible or inactive control, or not in any
  9230.      control, FindControl sets whichControl to NIL and returns 0 as its result.
  9231.  
  9232. Warning:  Notice that FindControl expects the mouse point in the window’s
  9233.           local coordinates, whereas FindWindow expects it in global
  9234.           coordinates. Always be sure to convert the point to local
  9235.           coordinates with the QuickDraw procedure GlobalToLocal before
  9236.           calling FindControl.
  9237.  
  9238. Note:  FindControl also returns NIL for whichControl and 0 as its result
  9239.        if the window is invisible or doesn’t contain the given point. In
  9240.        these cases, however, FindWindow wouldn’t have returned this window
  9241.        in the first place, so the situation should never arise.
  9242.  
  9243. æKY SetCtlColor
  9244. æFc Controls.h
  9245. æT Function
  9246. æTN AA43
  9247. æD pascal void SetCtlColor(ControlHandle theControl,CCTabHandle newColorTable)
  9248.     = 0xAA43; 
  9249. æDT SetCtlColor((ControlHandle) theControl,(CCTabHandle) newColorTable);
  9250. æMM
  9251. æRI V-222
  9252. æC 
  9253. [Macintosh II]
  9254.  
  9255. The SetCtlColor procedure sets or modifies a control’s color table.  If the control
  9256. currently has no auxiliary control record, a new one is created with the given color
  9257. table and added to the head of the auxiliary control list. If there is already an
  9258. auxiliary record for the control, its color table is replaced by the contents of
  9259. newColorTable.
  9260.  
  9261. If newColorTable has the same contents as the default color table, the
  9262. control’s existing auxiliary record and color table are removed from the auxiliary
  9263. control list and deallocated.  If theControl = NIL, the operation modifies the default
  9264. color table itself. If the control is visible, it will be redrawn by SetCtlColor
  9265. using the new color table.
  9266.  
  9267. æKY GetAuxCtl
  9268. æFc Controls.h
  9269. æT Function
  9270. æTN AA44
  9271. æD pascal Boolean GetAuxCtl(ControlHandle theControl,AuxCtlHandle *acHndl)
  9272.     = 0xAA44; 
  9273. æDT Boolean myVariable = GetAuxCtl((ControlHandle) theControl,(AuxCtlHandle *) acHndl);
  9274. æMM
  9275. æRI V-222
  9276. æC 
  9277. [Macintosh II]
  9278.  
  9279. The GetAuxCtl function returns a handle to a control’s AuxCtlRec:
  9280.  
  9281.   •  If the given control has its own color table, the function returns TRUE.
  9282.   •  If the control used the default color set, the function returns FALSE.
  9283.   •  If the control asked to receive the default color set (theControl = NIL),
  9284.      then the function returns TRUE.
  9285.  
  9286. æKY GetCVariant
  9287. æFc Controls.h
  9288. æT Function
  9289. æTN A809
  9290. æD pascal short GetCVariant(ControlHandle theControl)
  9291.     = 0xA809; 
  9292. æDT short myVariable = GetCVariant((ControlHandle) theControl);
  9293. æRI V-222
  9294. æC 
  9295. [Macintosh Plus, Macintosh SE, and Macintosh II]
  9296.  
  9297. The GetVariant function returns the variant control value for the control described
  9298. by theControl. This value was formerly stored in the high four bits of the control
  9299. defproc handle; for future compatibility, use the GetCVariant routine to access this
  9300. value.
  9301.  
  9302. æKY dragcontrol
  9303. æFc Controls.h
  9304. æT Function
  9305. æD void dragcontrol(ControlHandle theControl,Point *startPt,const Rect *limitRect,
  9306.     const Rect *slopRect,short axis); 
  9307. æDT dragcontrol((ControlHandle) theControl,(Point *) startPt,(const Rect *) limitRect,(
  9308.     const Rect) * slopRect,(short) axis);
  9309. æMM
  9310. æRI I-325
  9311. æC 
  9312. Called with the mouse button down inside theControl, DragControl pulls a dotted
  9313. outline of the control around the screen, following the movements of the mouse until
  9314. the button is released. When the mouse button is released, DragControl calls MoveControl
  9315. to move the control to the location to which it was dragged.
  9316.  
  9317. Note:  Before beginning to follow the mouse, DragControl calls the control
  9318.        definition function to allow it to do its own “custom dragging” if
  9319.        it chooses. If the definition function doesn’t choose to do any
  9320.        custom dragging, DragControl uses the default method of dragging
  9321.        described here.
  9322.  
  9323. The startPt, limitRect, slopRect, and axis parameters have the same meaning as for
  9324. the Window Manager function DragGrayRgn. These parameters are reviewed briefly below;
  9325. see the description of DragGrayRgn in the Window Manager chapter for more details.
  9326.  
  9327.   •  StartPt is assumed to be the point where the mouse button was originally
  9328.      pressed, in the local coordinates of the control’s window.
  9329.   •  LimitRect limits the travel of the control’s outline, and should normally
  9330.      coincide with or be contained within the window’s content region.
  9331.   •  SlopRect allows the user some “slop” in moving the mouse; it should
  9332.      completely enclose limitRect.
  9333.   •  The axis parameter allows you to constrain the control’s motion to
  9334.      only one axis. It has one of the following values:
  9335.  
  9336.        CONST  noConstraint = 0;    {no constraint}
  9337.               hAxisOnly    = 1;    {horizontal axis only}
  9338.               vAxisOnly    = 2;    {vertical axis only}
  9339.  
  9340. Assembly-language note:  Like TrackControl, DragControl invokes the
  9341.                          macro _DragTheRgn, so you can use the global
  9342.                          variables DragHook and DragPattern.
  9343.  
  9344. æKY newcontrol
  9345. æFc Controls.h
  9346. æT Function
  9347. æTN A954
  9348. æD ControlHandle newcontrol(WindowPtr theWindow,const Rect *boundsRect,char *title,
  9349.     Boolean visible,short value,short min,short max,short procID,long refCon); 
  9350. æDT ControlHandle myVariable = newcontrol((WindowPtr) theWindow,(const Rect *) boundsRect,(char *) title,()
  9351.     Boolean visible,(short) value,(short) min,(short) max,(short) procID,(long) refCon);
  9352. æMM
  9353. æRI I-319, P-112, 114, 177
  9354. æC  
  9355. NewControl creates a control, adds it to the beginning of theWindow’s control list,
  9356. and returns a handle to the new control. The values passed as parameters are stored
  9357. in the corresponding fields of the control record, as described below. The field that
  9358. determines highlighting is set to 0 (no highlighting) and the pointer to the default
  9359. action procedure is set to NIL (none).
  9360.  
  9361. Note:  The control definition function may do additional initialization,
  9362.        including changing any of the fields of the control record. The only
  9363.        standard control for which additional initialization is done is the
  9364.        scroll bar; its control definition function allocates space for a
  9365.        region to hold the thumb and stores the region handle in the
  9366.        contrlData field of the control record.
  9367.  
  9368. TheWindow is the window the new control will belong to. All coordinates pertaining to
  9369. the control will be interpreted in this window’s local coordinate system.
  9370.  
  9371. BoundsRect, given in theWindow’s local coordinates, is the rectangle that encloses
  9372. the control and thus determines its size and location. Note the following about the
  9373. enclosing rectangle for the standard controls:
  9374.  
  9375.   •  Simple buttons are drawn to fit the rectangle exactly. (The control
  9376.      definition function calls the QuickDraw procedure FrameRoundRect.) To
  9377.      allow for the tallest characters in the system font, there should be
  9378.      at least a 20-point difference between the top and bottom coordinates
  9379.      of the rectangle.
  9380.   •  For check boxes and radio buttons, there should be at least a 16-point
  9381.      difference between the top and bottom coordinates.
  9382.   •  By convention, scroll bars are 16 pixels wide, so there should be a
  9383.      16-point difference between the left and right (or top and bottom)
  9384.      coordinates. (If there isn’t, the scroll bar will be scaled to fit
  9385.      the rectangle.) A standard scroll bar should be at least 48 pixels
  9386.      long, to allow room for the scroll arrows and thumb.
  9387.  
  9388. Title is the control’s title, if any (if none, you can just pass the empty string as
  9389. the title). Be sure the title will fit in the control’s enclosing rectangle; if it
  9390. won’t it will be truncated on the right for check boxes and radio buttons, or centered
  9391. and truncated on both ends for simple buttons.
  9392.  
  9393. Note:  Some non-Roman systems write text from right-to-left, in which
  9394.        case radio buttons and check boxes are drawn with their titles
  9395.        on the left of the control.  They are also truncated on the left.
  9396.        See the Script Manager chapter for more information.
  9397.  
  9398. If the visible parameter is TRUE, NewControl draws the control.
  9399.  
  9400. Note:  It does not use the standard window updating mechanism, but
  9401.        instead draws the control immediately in the window.
  9402.  
  9403. The min and max parameters define the control’s range of possible settings; the value
  9404. parameter gives the initial setting. For controls that don’t retain a setting, such
  9405. as buttons, the values you supply for these parameters will be stored in the control
  9406. record but will never be used. So it doesn’t matter what values you give for those
  9407. controls—0 for all three parameters will do. For controls that just retain an on-or-off
  9408. setting, such as check boxes or radio buttons, min should be 0 (meaning the control
  9409. is off) and max should be 1
  9410. (meaning it’s on). For dials, you can specify whatever values are appropriate for
  9411. min, max, and value.
  9412.  
  9413. ProcID is the control definition ID, which leads to the control definition function
  9414. for this type of control. (The function is read into memory if it
  9415. isn’t already in memory.) The control definition IDs for the standard control types
  9416. are listed above under “Controls and Resources”. Control definition IDs for custom
  9417. control types are discussed later under “Defining Your Own Controls”.
  9418.  
  9419. RefCon is the control’s reference value, set and used only by your application.
  9420.  
  9421. æKY findcontrol
  9422. æFc Controls.h
  9423. æT Function
  9424. æD short findcontrol(Point *thePoint,WindowPtr theWindow,ControlHandle *theControl); 
  9425. æDT short myVariable = findcontrol((Point *) thePoint,(WindowPtr) theWindow,(ControlHandle *) theControl);
  9426. æMM
  9427. æRI I-323, P-98, 114, 170
  9428. æC  
  9429. When the Window Manager function FindWindow reports that the mouse button was pressed
  9430. in the content region of a window, and the window contains controls, the application
  9431. should call FindControl with theWindow equal to the window pointer and thePoint equal
  9432. to the point where the mouse button was pressed (in the window’s local coordinates).
  9433. FindControl tells which of the window’s controls, if any, the mouse button was pressed
  9434. in:
  9435.  
  9436.   •  If it was pressed in a visible, active control, FindControl sets the
  9437.      whichControl parameter to the control handle and returns a part code
  9438.      identifying the part of the control that it was pressed in.
  9439.   •  If it was pressed in an invisible or inactive control, or not in any
  9440.      control, FindControl sets whichControl to NIL and returns 0 as its result.
  9441.  
  9442. Warning:  Notice that FindControl expects the mouse point in the window’s
  9443.           local coordinates, whereas FindWindow expects it in global
  9444.           coordinates. Always be sure to convert the point to local
  9445.           coordinates with the QuickDraw procedure GlobalToLocal before
  9446.           calling FindControl.
  9447.  
  9448. Note:  FindControl also returns NIL for whichControl and 0 as its result
  9449.        if the window is invisible or doesn’t contain the given point. In
  9450.        these cases, however, FindWindow wouldn’t have returned this window
  9451.        in the first place, so the situation should never arise.
  9452.  
  9453. æKY getctitle
  9454. æFc Controls.h
  9455. æT Function
  9456. æD void getctitle(ControlHandle theControl,char *title); 
  9457. æDT getctitle((ControlHandle) theControl,(char *) title);
  9458. æRI I-321
  9459. æC 
  9460. GetCTitle returns theControl’s title as the value of the title parameter.
  9461.  
  9462. æKY setctitle
  9463. æFc Controls.h
  9464. æT Function
  9465. æD void setctitle(ControlHandle theControl,char *title); 
  9466. æDT setctitle((ControlHandle) theControl,(char *) title);
  9467. æMM
  9468. æRI I-321
  9469. æC  
  9470. SetCTitle sets theControl’s title to the given string and redraws the control.
  9471.  
  9472. æKY trackcontrol
  9473. æFc Controls.h
  9474. æT Function
  9475. æD short trackcontrol(ControlHandle theControl,Point *thePoint,ProcPtr actionProc); 
  9476. æDT short myVariable = trackcontrol((ControlHandle) theControl,(Point *) thePoint,(ProcPtr) actionProc);
  9477. æMM
  9478. æRI I-323, P-114, 184
  9479. æC 
  9480. When the mouse button is pressed in a visible, active control, the application should
  9481. call TrackControl with theControl equal to the control handle and startPt equal to
  9482. the point where the mouse button was pressed (in the local coordinates of the control’s
  9483. window). TrackControl follows the movements of the mouse and responds in whatever way
  9484. is appropriate until the mouse button is released; the exact response depends on the
  9485. type of control and the part of the control in which the mouse button was pressed. If
  9486. highlighting is appropriate, TrackControl does the highlighting, and undoes it before
  9487. returning. When the mouse button is released, TrackControl returns with the part code
  9488. if the mouse is in the same part of the control that it was originally in, or with 0
  9489. if not
  9490. (in which case the application should do nothing).
  9491.  
  9492. If the mouse button was pressed in an indicator, TrackControl drags a dotted outline
  9493. of it to follow the mouse. When the mouse button is released, TrackControl calls the
  9494. control definition function to reposition the control’s indicator. The control definition
  9495. function for scroll bars responds by redrawing the thumb, calculating the control’s
  9496. current setting based on the new relative position of the thumb, and storing the
  9497. current setting in the control record; for example, if the minimum and maximum settings
  9498. are 0 and 10, and the thumb is in the middle of the scroll bar, 5 is stored as the
  9499. current setting. The application must then scroll to the corresponding relative
  9500. position in the document.
  9501.  
  9502. TrackControl may take additional actions beyond highlighting the control or dragging
  9503. the indicator, depending on the value passed in the actionProc parameter, as described
  9504. below. The following tells you what to pass for the standard control types; for a
  9505. custom control, what you pass will depend on how the control is defined.
  9506.  
  9507.   •  If actionProc is NIL, TrackControl performs no additional actions. This
  9508.      is appropriate for simple buttons, check boxes, radio buttons, and the
  9509.      thumb of a scroll bar.
  9510.   •  ActionProc may be a pointer to an action procedure that defines some
  9511.      action to be performed repeatedly for as long as the user holds down
  9512.      the mouse button. (See below for details.)
  9513.   •  If actionProc is POINTER(–1), TrackControl looks in the control record
  9514.      for a pointer to the control’s default action procedure. If that field
  9515.      of the control record contains a procedure pointer, TrackControl uses
  9516.      the action procedure it points to; if the field contains POINTER (–1),
  9517.      TrackControl calls the control definition function to perform the
  9518.      necessary action. (If the field contains NIL, TrackControl does nothing.)
  9519.  
  9520. The action procedure in the control definition function is described in the section
  9521. “Defining Your Own Controls”. The following paragraphs describe only the action
  9522. procedure whose pointer is passed in the actionProc parameter or stored in the control
  9523. record.
  9524.  
  9525. If the mouse button was pressed in an indicator, the action procedure (if any) should
  9526. have no parameters. This procedure must allow for the fact that the mouse may not be
  9527. inside the original control part.
  9528.  
  9529. If the mouse button was pressed in a control part other than an indicator, the action
  9530. procedure should be of the form
  9531.  
  9532. PROCEDURE MyAction (theControl:  ControlHandle; partCode:  INTEGER);
  9533.  
  9534. In this case, TrackControl passes the control handle and the part code to the action
  9535. procedure. (It passes 0 in the partCode parameter if the mouse has moved outside the
  9536. original control part.) As an example of this type of action procedure, consider what
  9537. should happen when the mouse button is pressed in a scroll arrow or paging region in
  9538. a scroll bar. For these cases, your action procedure should examine the part code to
  9539. determine exactly where the mouse button was pressed, scroll up or down a line or
  9540. page as appropriate, and call SetCtlValue to change the control’s setting and redraw
  9541. the thumb.
  9542.  
  9543. Warning:  Since it has a different number of parameters depending on whether
  9544.           the mouse button was pressed in an indicator or elsewhere, the
  9545.           action procedure you pass to TrackControl (or whose pointer you
  9546.           store in the control record) can be set up for only one case or
  9547.           the other. If you store a pointer to a default action procedure
  9548.           in a control record, be sure it will be used only when appropriate
  9549.           for that type of action procedure. The only way to specify actions
  9550.           in response to all mouse-down events in a control, regardless of
  9551.           whether they’re in an indicator, is via the control definition
  9552.           function.
  9553.  
  9554. Assembly-language note:  If you store a pointer to a procedure in the global
  9555.                          variable DragHook, that procedure will be called
  9556.                          repeatedly (with no parameters) for as long as the
  9557.                          user holds down the mouse button. TrackControl
  9558.                          invokes the Window Manager macro _DragTheRgn,
  9559.                          which calls the DragHook procedure. _DragTheRgn
  9560.                          uses the pattern stored in the global variable
  9561.                          DragPattern for the dragged outline of the indicator.
  9562.  
  9563. æKY testcontrol
  9564. æFc Controls.h
  9565. æT Function
  9566. æD short testcontrol(ControlHandle theControl,Point *thePt); 
  9567. æDT short myVariable = testcontrol((ControlHandle) theControl,(Point *) thePt);
  9568. æMM
  9569. æRI I-325
  9570. æC  
  9571. If theControl is visible and active, TestControl tests which part of the control
  9572. contains thePoint (in the local coordinates of the control’s window); it returns the
  9573. corresponding part code, or 0 if the point is outside the control. If the control is
  9574. invisible or inactive, TestControl returns 0. TestControl is called by FindControl
  9575. and TrackControl; normally you won’t need to call it yourself.
  9576.  
  9577.  
  9578. æKY Ctype.h
  9579. æKL _tolower
  9580. _toupper
  9581. isalnum
  9582. isalpha
  9583. isascii
  9584. iscntrl
  9585. isdigit
  9586. isgraph
  9587. islower
  9588. isprint
  9589. ispunct
  9590. isspace
  9591. isupper
  9592. isxdigit
  9593. toascii
  9594. tolower
  9595. toupper
  9596.  
  9597. æKY isalpha
  9598. isupper
  9599. islower
  9600. isdigit
  9601. isxdigit
  9602. isalnum
  9603. isspace
  9604. ispunct
  9605. isprint
  9606. isgraph
  9607. iscntrl
  9608. isascii
  9609. æFc CType.h
  9610. æC These functions tell whether a given character is in one of 
  9611. several categories: alphabetical, uppercase, lowercase, digit, 
  9612. hex digit, white-space, punctuation mark, printing, graphic, or 
  9613. control. A separate function is provided for each category.
  9614.  
  9615.                           Synopsis
  9616.  
  9617. #include <CType.h>
  9618. int isalpha(int c);
  9619. int isupper(int c);
  9620. int islower(int c);
  9621. int isdigit(int c);
  9622. int isxdigit(int c);
  9623. int isalnum(int c);
  9624. int isspace(int c);
  9625. int ispunct(int c);
  9626. int isprint(int c);
  9627. int isgraph(int c);
  9628. int iscntrl(int c);
  9629. int isascii(int c);
  9630.  
  9631.                            Description
  9632.  
  9633. These macros return nonzero for true, zero for false, 
  9634. depending on the corresponding integer value of the given 
  9635. character. The isascii macro is defined on all integer values; 
  9636. the rest are defined only where isascii is true and on the 
  9637. single non-ASCII value EOF(–1).  
  9638.  
  9639. Table 3-1 shows when these macros return the value true.
  9640. Table 3-1    Character-testing macros
  9641.  
  9642. Macro    Returns true if
  9643.  
  9644. isascii; c is an ASCII character code lower than128.
  9645. isalpha; c is a letter [A–Z] or [a–z].
  9646. isupper; c is an uppercase letter [A–Z].
  9647. islower; c is a lowercase letter [a–z].
  9648. isdigit; c is a digit [0–9].
  9649. isxdigit; c is a hexadecimal digit [0–9], [A–F], or [a–f].
  9650. isalnum; c is alphanumeric (letter or digit).
  9651. isspace; c is a space, tab, return, new line, vertical tab, or form feed.
  9652. ispunct; c is a punctuation character (neither control nor alphanumeric).
  9653. isprint; c is a printing character, space (32) through tilde (126).
  9654. isgraph; c is a printing character, similar to isprint except false for space.
  9655. iscntrl; c is a delete character (127) or an ordinary control character 
  9656.  (less than 32).
  9657.  
  9658.                            Note
  9659.  
  9660. These macros do not support the Macintosh extended character 
  9661. set. For values outside the domain, the result is undefined.
  9662.  
  9663.                            Warning
  9664.  
  9665. If c is not in the domain of the function, the result is undefined.  
  9666.  
  9667. See also
  9668. Character case
  9669.  
  9670. æKY toupper
  9671. tolower
  9672. _toupper
  9673. _tolower
  9674. toascii
  9675. æFc CType.h
  9676. æC The first four of these routines change the case of a character. 
  9677. The toascii function converts any character to an ASCII character.
  9678.  
  9679.                           Synopsis
  9680.  
  9681. #include <CType.h>
  9682. int toupper(int c);
  9683. int tolower(int c);
  9684. int _toupper(int c);
  9685. int _tolower(int c);
  9686. int toascii(int c);
  9687.  
  9688.                            Description
  9689.  
  9690. The toupper; and tolower; functions have as their domain the 
  9691. set of ASCII characters (0 through 127) and the constant EOF (–
  9692. 1). If parameter c to toupper represents a lowercase letter, the 
  9693. result is the corresponding uppercase letter. If parameter c to 
  9694. tolower represents an uppercase letter, the result is the 
  9695. corresponding lowercase letter. All other parameters in the 
  9696. domain are returned unchanged.
  9697.  
  9698. The _toupper; and _tolower; macros produce the same 
  9699. results as functions toupper and tolower but have restricted 
  9700. domains and are faster. Macro _toupper requires a lowercase 
  9701. letter as its parameter; its result is the corresponding 
  9702. uppercase letter. Macro _tolower requires an uppercase letter 
  9703. as its parameter; its result is the corresponding lowercase 
  9704. letter. Parameters outside the domain cause undefined results.
  9705. The toascii; macro converts c by clearing all bits that are not 
  9706. part of a standard ASCII character. It is used for compatibility 
  9707. with other systems.
  9708.  
  9709.                            Note
  9710.  
  9711. These routines do not support the Macintosh extended 
  9712. character set (with values greater than 0x7F). For values 
  9713. outside the stated domain, the result is undefined.
  9714.  
  9715.                            Warning
  9716.  
  9717. The _toupper and _tolower macros must be used with care: 
  9718. parameters outside their respective domains cause undefined 
  9719. results. The _toupper macro requires a lowercase letter as its 
  9720. parameter: the _tolower macro requires an uppercase letter as 
  9721. its parameter.
  9722.  
  9723. See also
  9724. Character testing
  9725.  
  9726.  
  9727. æKY isalphaæ
  9728. æDT 
  9729. int myVariable = isalpha((int) c);
  9730.  
  9731. æKY isupperæ
  9732. æDT 
  9733. int myVariable = isupper((int) c);
  9734.  
  9735. æKY isloweræ
  9736. æDT 
  9737. int myVariable = islower((int) c);
  9738.  
  9739. æKY isdigitæ
  9740. æDT 
  9741. int myVariable = isdigit((int) c);
  9742.  
  9743. æKY isxdigitæ
  9744. æDT 
  9745. int myVariable = isxdigit((int) c);
  9746.  
  9747. æKY isalnumæ
  9748. æDT 
  9749. int myVariable = isalnum((int) c);
  9750.  
  9751. æKY isspaceæ
  9752. æDT 
  9753. int myVariable = isspace((int) c);
  9754.  
  9755.  
  9756. æKY ispunctæ
  9757. æDT 
  9758. int myVariable = ispunct((int) c);
  9759.  
  9760.  
  9761. æKY isprintæ
  9762. æDT 
  9763. int myVariable = isprint((int) c);
  9764.  
  9765. æKY isgraphæ
  9766. æDT 
  9767. int myVariable = isgraph((int) c);
  9768.  
  9769. æKY iscntrlæ
  9770. æDT 
  9771. int myVariable = iscntrl((int) c);
  9772.  
  9773. æKY isasciiæ
  9774. æDT 
  9775. int my Variable = isascii((int) c);
  9776.  
  9777.  
  9778. æKY toupperæ
  9779. æDT 
  9780. int myVariable = toupper((int) c);
  9781.  
  9782. æKY toloweræ
  9783. æDT 
  9784. int myVariable = tolower((int) c);
  9785.  
  9786. æKY _toupperæ
  9787. æDT 
  9788. int myVariable =  _toupper((int) c);
  9789.  
  9790.  
  9791. æKY _toloweræ
  9792. æDT 
  9793. int myVariable =  _toupper((int) c);
  9794.  
  9795.  
  9796. æKY toasciiæ
  9797. æDT 
  9798. int myVariable = toascii((int) c);
  9799.  
  9800.  
  9801. æKY CursorCtl.h
  9802. æKL Hide_Cursor
  9803. InitCursorCtl
  9804. RotateCursor
  9805. Show_Cursor
  9806. SpinCursor
  9807.  
  9808. acur
  9809. Acur
  9810. acurHandle
  9811. acurPtr
  9812. ARROW_CURSOR
  9813. CROSS_CURSOR
  9814. Cursors
  9815. HIDDEN_CURSOR
  9816. I_BEAM_CURSOR
  9817. PLUS_CURSOR
  9818. WATCH_CURSOR
  9819.  
  9820. æKY Acur
  9821. acur
  9822. acurPtr
  9823. acurHandle
  9824. æFc CursorCtl.h
  9825. æT struct
  9826. æD struct Acur {
  9827.     short n;        /*Number of cursors ("frames of film")*/
  9828.     short index;    /* Next frame to show <for internal use>*/
  9829.     short frame1;   /*'CURS' resource id for frame #1*/
  9830.     short fill1;    /*<for internal use>*/
  9831.     short frame2;   /*'CURS' resource id for frame #2*/
  9832.     short fill2;    /*<for internal use>*/
  9833.     short frameN;   /*'CURS' resource id for frame #N*/
  9834.     short fillN;    /*<for internal use>*/
  9835. };
  9836. typedef struct Acur acur,*acurPtr,**acurHandle;
  9837.  
  9838. æKY Cursors
  9839. HIDDEN_CURSOR
  9840. I_BEAM_CURSOR
  9841. CROSS_CURSOR
  9842. PLUS_CURSOR
  9843. WATCH_CURSOR
  9844. ARROW_CURSOR
  9845. æFc CursorCtl.h
  9846. æD enum {HIDDEN_CURSOR,I_BEAM_CURSOR,CROSS_CURSOR,PLUS_CURSOR,WATCH_CURSOR,
  9847. ARROW_CURSOR}Cursors;
  9848. typedef unsigned char Cursors;
  9849.  
  9850. æKY Hide_Cursor
  9851. æFc CursorCtl.h
  9852. æT Function
  9853. æD pascal void Hide_Cursor(void);
  9854. æDT Hide_Cursor();
  9855. æC 
  9856. /* 
  9857.     Hide the cursor if it is showing.This is this unit's call to the Mac
  9858.     HideCursor routine.Thus the Mac cursor level is decremented by one when this
  9859.     routine is called.
  9860. */
  9861.  
  9862. æKY InitCursorCtl
  9863. æFc CursorCtl.h
  9864. æT Function
  9865. æD pascal void InitCursorCtl(acurHandle newCursors);
  9866. æDT InitCursorCtl((acurHandle)newCursors);
  9867. æC 
  9868. /* 
  9869.     Initialize the CursorCtl unit. This should be called once prior to calling
  9870.     RotateCursor or SpinCursor. It need not be called if only Hide_Cursor or
  9871.     Show_Cursor are used. If NewCursors is NULL, InitCursorCtl loads in the
  9872.     'acur' resource and the 'CURS' resources specified by the 'acur' resource
  9873.     ids.  If any of the resources cannot be loaded, the cursor will not be
  9874.     changed.
  9875.     
  9876.     The 'acur' resource is assumed to either be in the currently running tool or
  9877.     application, or the MPW Shell for a tool, or in the System file.  The 'acur'
  9878.     resource id must be 0 for a tool or application, 1 for the Shell, and 2 for
  9879.     the System file.
  9880.     
  9881.     If NewCursors is not NULL, it is ASSUMED to be a handle to an 'acur' formatted
  9882.     resource designated by the caller and it will be used instead of doing a
  9883.     GetResource on 'acur'. Note, if RotateCursor or SpinCursor are called without
  9884.     calling InitCursorCtl, then RotateCursor and SpinCursor will do the call for
  9885.     the user the first time it is called.  However, the possible disadvantage of
  9886.     using this technique is that the resource memory allocated may have
  9887.     undesirable affect (fragmentation?) on the application. Using InitCursorCtl
  9888.     has the advantage of causing the allocation at a specific time determined by
  9889.     the user.
  9890.     
  9891.     Caution: InitCursorCtl MODIFIES the 'acur' resource in memory.  Specifically,
  9892.     it changes each FrameN/fillN integer pair to a handle to the corresponding
  9893.     'CURS' resource also in memory.  Thus if NewCursors is not NULL when
  9894.     InitCursorCtl is called, the caller must guarantee NewCursors always points to
  9895.     a "fresh" copy of an 'acur' resource.  This need only be of concern to a
  9896.     caller who wants to repeatly use multiple 'acur' resources during execution of
  9897.     their programs.
  9898. */
  9899.  
  9900. æKY RotateCursor
  9901. æFc CursorCtl.h
  9902. æT Function
  9903. æD pascal void RotateCursor(long counter);
  9904. æDT RotateCursor((long)counter);
  9905. æC 
  9906. /* 
  9907.     RotateCursor is called to rotate the "I am active" "beach ball" cursor, or to
  9908.     animate whatever sequence of cursors set up by InitCursorCtl. The next cursor
  9909.     ("frame") is used when Counter % 32 = 0 (Counter is some kind of incrementing
  9910.     or decrementing index maintained by the caller). A positive counter sequences
  9911.     forward through the cursors (e.g., it rotates the "beach ball" cursor
  9912.     clockwise), and a negative cursor sequences through the cursors backwards
  9913.     (e.g., it rotates the "beach ball" cursor counterclockwise).  Note,
  9914.     RotateCursor just does a Mac SetCursor call for the proper cursor picture.
  9915.       It is assumed the cursor is visible from a prior Show_Cursor call.
  9916. */
  9917.  
  9918. æKY Show_Cursor
  9919. æFc CursorCtl.h
  9920. æT Function
  9921. æD pascal void Show_Cursor(Cursors cursorKind);
  9922. æDT Show_Cursor((Cursors)cursorKind);
  9923. æC 
  9924. /* 
  9925.     Increment the cursor level, which may have been decremented by Hide_Cursor,
  9926.     and display the specified cursor if the level becomes 0 (it is never
  9927.     incremented beyond 0).The CursorKind is the kind of cursor to show.  It is
  9928.     one of the values HIDDEN_CURSOR, I_BEAM_CURSOR, CROSS_CURSOR, PLUS_CURSOR,
  9929.     WATCH_CURSOR, and ARROW_CURSOR. Except for HIDDEN_CURSOR, a Mac SetCursor is 
  9930.     done for the specified cursor prior to doing a ShowCursor.  HIDDEN_CURSOR just
  9931.     causes a ShowCursor call.  Note, ARROW_CURSOR will only work correctly if
  9932.     there is already a grafPort set up pointed to by 0(A5).
  9933. */
  9934.  
  9935. æKY SpinCursor
  9936. æFc CursorCtl.h
  9937. æT Function
  9938. æD pascal void SpinCursor(short increment);
  9939. æDT SpinCursor((short)increment);
  9940. æC 
  9941. /* 
  9942.     SpinCursor is similar in function to RotateCursor, except that instead of
  9943.     passing a counter, an Increment is passed an added to a counter maintained
  9944.     here.  SpinCursor is provided for those users who do not happen to have a
  9945.     convenient counter handy but still want to use the spinning "beach ball"
  9946.     cursor, or any sequence of cursors set up by InitCursorCtl.  A positive 
  9947.     increment sequences forward through the curos (rotating the "beach ball"
  9948.     cursor clockwise), and a negative increment sequences backward through the
  9949.     cursors (rotating the "beach ball" cursor counter-clockwise).  A zero value
  9950.     for the increment resets the counter to zero.  Note, it is the increment, and
  9951.     not the value of the counter that determines the sequencing direction of the
  9952.     cursor (and hence the spin direction of the "beach ball" cursor).
  9953. */
  9954.  
  9955.  
  9956.  
  9957. æKY DatabaseAccess.h
  9958. æKL DBBreak
  9959. DBDisposeQuery
  9960. DBEnd
  9961. DBExec
  9962. DBGetConnInfo
  9963. DBGetErr
  9964. DBGetItem
  9965. DBGetNewQuery
  9966. DBGetQueryResults
  9967. DBGetResultHandler
  9968. DBGetSessionNum
  9969. DBInit
  9970. DBInstallResultHandler
  9971. DBKill
  9972. DBRemoveResultHandler
  9973. DBResultsToText
  9974. DBSend
  9975. DBSendItem
  9976. DBStartQuery
  9977. DBState
  9978. DBUnGetItem
  9979. InitDBPack
  9980. QuitDBPack
  9981.  
  9982. DBAsyncParamBlockRec
  9983. DBAsyncParmBlkPtr
  9984. DBColInfoRecord
  9985. DBType
  9986. kDBAboutToInit
  9987. kDBExecComplete
  9988. kDBGetItemComplete
  9989. kDBGetQueryResultsComplete
  9990. kDBInitComplete
  9991. kDBLastColFlag
  9992. kDBSendComplete
  9993. kDBStartQueryComplete
  9994. kDBUpdateWind
  9995. kDBWaitForever
  9996. QueryHandle
  9997. QueryListHandle
  9998. QueryPtr
  9999. QueryRecord
  10000. rcDBAsyncNotSupp
  10001. rcDBBadAsyncPB
  10002. rcDBBadDDEV
  10003. rcDBBadSessID
  10004. rcDBBadSessNum
  10005. rcDBBadType
  10006. rcDBBreak
  10007. rcDBError
  10008. rcDBExec
  10009. rcDBNoHandler
  10010. rcDBNull
  10011. rcDBPackNotInited
  10012. rcDBValue
  10013. rcDBWrongVersion
  10014. ResListElem
  10015. ResListHandle
  10016. ResultsRecord
  10017. typeAnyType
  10018. typeBoolean
  10019. typeChar
  10020. typeColBreak
  10021. typeDate
  10022. typeDecimal
  10023. typeDiscard
  10024. typeFloat
  10025. typeInteger
  10026. typeLBin
  10027. typeLChar
  10028. typeMoney
  10029. typeNone
  10030. typeRowBreak
  10031. typeSMFloat
  10032. typeSMInt
  10033. typeTime
  10034. typeTimeStamp
  10035. typeUnknown
  10036. typeVBin
  10037. typeVChar
  10038.  
  10039. æKY rcDBNull
  10040. æFc DatabaseAccess.h
  10041. æT #define
  10042. æD 
  10043. /*  OSErr error and status codes  */
  10044.  
  10045. #define rcDBNull -800
  10046. æC 
  10047.  
  10048. æKY rcDBValue
  10049. æFc DatabaseAccess.h
  10050. æT #define
  10051. æD #define rcDBValue -801
  10052. æC 
  10053.  
  10054. æKY rcDBError
  10055. æFc DatabaseAccess.h
  10056. æT #define
  10057. æD #define rcDBError -802
  10058. æC 
  10059.  
  10060. æKY rcDBBadType
  10061. æFc DatabaseAccess.h
  10062. æT #define
  10063. æD #define rcDBBadType -803
  10064. æC 
  10065.  
  10066. æKY rcDBBreak
  10067. æFc DatabaseAccess.h
  10068. æT #define
  10069. æD #define rcDBBreak -804
  10070. æC 
  10071.  
  10072. æKY rcDBExec
  10073. æFc DatabaseAccess.h
  10074. æT #define
  10075. æD #define rcDBExec -805
  10076. æC 
  10077.  
  10078. æKY rcDBBadSessID
  10079. æFc DatabaseAccess.h
  10080. æT #define
  10081. æD #define rcDBBadSessID -806
  10082. æC 
  10083.  
  10084. æKY rcDBBadSessNum
  10085. æFc DatabaseAccess.h
  10086. æT #define
  10087. æD #define rcDBBadSessNum -807 /* bad session number for DBGetConnInfo */
  10088. æC 
  10089.  
  10090. æKY rcDBBadDDEV
  10091. æFc DatabaseAccess.h
  10092. æT #define
  10093. æD #define rcDBBadDDEV -808 /* bad ddev specified on DBInit */
  10094. æC 
  10095.  
  10096. æKY rcDBAsyncNotSupp
  10097. æFc DatabaseAccess.h
  10098. æT #define
  10099. æD #define rcDBAsyncNotSupp -809 /* ddev does not support async calls */
  10100. æC 
  10101.  
  10102. æKY rcDBBadAsyncPB
  10103. æFc DatabaseAccess.h
  10104. æT #define
  10105. æD #define rcDBBadAsyncPB -810 /* tried to kill a bad pb */
  10106. æC 
  10107.  
  10108. æKY rcDBNoHandler
  10109. æFc DatabaseAccess.h
  10110. æT #define
  10111. æD #define rcDBNoHandler -811 /* no app handler for specified data type */
  10112. æC 
  10113.  
  10114. æKY rcDBWrongVersion
  10115. æFc DatabaseAccess.h
  10116. æT #define
  10117. æD #define rcDBWrongVersion -812 /* incompatible versions */
  10118. æC 
  10119.  
  10120. æKY rcDBPackNotInited
  10121. æFc DatabaseAccess.h
  10122. æT #define
  10123. æD #define rcDBPackNotInited -813 /* attempt to call other routine before InitDBPack */
  10124. æC 
  10125.  
  10126. æKY kDBUpdateWind
  10127. æFc DatabaseAccess.h
  10128. æT #define
  10129. æD 
  10130. /*  messages for status functions for DBStartQuery  */
  10131.  
  10132. #define kDBUpdateWind 0
  10133. æC 
  10134.  
  10135. æKY kDBAboutToInit
  10136. æFc DatabaseAccess.h
  10137. æT #define
  10138. æD #define kDBAboutToInit 1
  10139. æC 
  10140.  
  10141. æKY kDBInitComplete
  10142. æFc DatabaseAccess.h
  10143. æT #define
  10144. æD #define kDBInitComplete 2
  10145. æC 
  10146.  
  10147. æKY kDBSendComplete
  10148. æFc DatabaseAccess.h
  10149. æT #define
  10150. æD #define kDBSendComplete 3
  10151. æC 
  10152.  
  10153. æKY kDBExecComplete
  10154. æFc DatabaseAccess.h
  10155. æT #define
  10156. æD #define kDBExecComplete 4
  10157. æC 
  10158.  
  10159. æKY kDBStartQueryComplete
  10160. æFc DatabaseAccess.h
  10161. æT #define
  10162. æD #define kDBStartQueryComplete 5
  10163. æC 
  10164.  
  10165. æKY kDBGetItemComplete
  10166. æFc DatabaseAccess.h
  10167. æT #define
  10168. æD 
  10169. /*  messages for status functions for DBGetQueryResults  */
  10170.  
  10171. #define kDBGetItemComplete 6
  10172. æC 
  10173.  
  10174. æKY kDBGetQueryResultsComplete
  10175. æFc DatabaseAccess.h
  10176. æT #define
  10177. æD #define kDBGetQueryResultsComplete 7
  10178. æC 
  10179.  
  10180. æKY typeNone
  10181. æFc DatabaseAccess.h
  10182. æT #define
  10183. æD 
  10184. /*  data type codes  */
  10185.  
  10186. #define typeNone 'none'
  10187. æC 
  10188.  
  10189. æKY typeBoolean
  10190. æFc DatabaseAccess.h
  10191. æT #define
  10192. æD #define typeBoolean 'bool'
  10193. æC 
  10194.  
  10195. æKY typeSMInt
  10196. æFc DatabaseAccess.h
  10197. æT #define
  10198. æD #define typeSMInt 'smin'
  10199. æC 
  10200.  
  10201. æKY typeInteger
  10202. æFc DatabaseAccess.h
  10203. æT #define
  10204. æD #define typeInteger 'int '
  10205. æC 
  10206.  
  10207. æKY typeSMFloat
  10208. æFc DatabaseAccess.h
  10209. æT #define
  10210. æD #define typeSMFloat 'smfl'
  10211. æC 
  10212.  
  10213. æKY typeFloat
  10214. æFc DatabaseAccess.h
  10215. æT #define
  10216. æD #define typeFloat 'flot'
  10217. æC 
  10218.  
  10219. æKY typeDate
  10220. æFc DatabaseAccess.h
  10221. æT #define
  10222. æD #define typeDate 'date'
  10223. æC 
  10224.  
  10225. æKY typeTime
  10226. æFc DatabaseAccess.h
  10227. æT #define
  10228. æD #define typeTime 'time'
  10229. æC 
  10230.  
  10231. æKY typeTimeStamp
  10232. æFc DatabaseAccess.h
  10233. æT #define
  10234. æD #define typeTimeStamp 'tims'
  10235. æC 
  10236.  
  10237. æKY typeChar
  10238. æFc DatabaseAccess.h
  10239. æT #define
  10240. æD #define typeChar 'char'
  10241. æC 
  10242.  
  10243. æKY typeDecimal
  10244. æFc DatabaseAccess.h
  10245. æT #define
  10246. æD #define typeDecimal 'decm'
  10247. æC 
  10248.  
  10249. æKY typeMoney
  10250. æFc DatabaseAccess.h
  10251. æT #define
  10252. æD #define typeMoney 'mony'
  10253. æC 
  10254.  
  10255. æKY typeVChar
  10256. æFc DatabaseAccess.h
  10257. æT #define
  10258. æD #define typeVChar 'vchr'
  10259. æC 
  10260.  
  10261. æKY typeVBin
  10262. æFc DatabaseAccess.h
  10263. æT #define
  10264. æD #define typeVBin 'vbin'
  10265. æC 
  10266.  
  10267. æKY typeLChar
  10268. æFc DatabaseAccess.h
  10269. æT #define
  10270. æD #define typeLChar 'lchr'
  10271. æC 
  10272.  
  10273. æKY typeLBin
  10274. æFc DatabaseAccess.h
  10275. æT #define
  10276. æD #define typeLBin 'lbin'
  10277. æC 
  10278.  
  10279. æKY typeDiscard
  10280. æFc DatabaseAccess.h
  10281. æT #define
  10282. æD #define typeDiscard 'disc'
  10283. æC 
  10284.  
  10285. æKY typeUnknown
  10286. æFc DatabaseAccess.h
  10287. æT #define
  10288. æD 
  10289. /*  "dummy" types for DBResultsToText  */
  10290.  
  10291. #define typeUnknown 'unkn'
  10292. æC 
  10293.  
  10294. æKY typeColBreak
  10295. æFc DatabaseAccess.h
  10296. æT #define
  10297. æD #define typeColBreak 'cbrk'
  10298. æC 
  10299.  
  10300. æKY typeRowBreak
  10301. æFc DatabaseAccess.h
  10302. æT #define
  10303. æD #define typeRowBreak 'rbrk'
  10304. æC 
  10305.  
  10306. æKY typeAnyType
  10307. æFc DatabaseAccess.h
  10308. æT #define
  10309. æD 
  10310. /*  pass this in to DBGetItem for any data type  */
  10311.  
  10312. #define typeAnyType (DBType)0
  10313. æC 
  10314.  
  10315. æKY kDBWaitForever
  10316. æFc DatabaseAccess.h
  10317. æT #define
  10318. æD 
  10319. /*  infinite timeout value for DBGetItem  */
  10320.  
  10321. #define kDBWaitForever -1
  10322. æC 
  10323.  
  10324. æKY kDBLastColFlag
  10325. æFc DatabaseAccess.h
  10326. æT #define
  10327. æD 
  10328. /*  flag for last column in row for DBGetItem  */
  10329.  
  10330. #define kDBLastColFlag 0x0001
  10331. æC 
  10332.  
  10333. æKY DBType
  10334. æFc DatabaseAccess.h
  10335. æT typedef
  10336. æD typedef OSType DBType;
  10337. æC 
  10338.  
  10339. æKY QueryListHandle
  10340. æFc DatabaseAccess.h
  10341. æT typedef
  10342. æD typedef Handle **QueryListHandle; /* just handles to 'wstr' resources */
  10343. æC 
  10344.  
  10345. æKY DBAsyncParamBlockRec
  10346. DBAsyncParmBlkPtr
  10347. æFc DatabaseAccess.h
  10348. æT struct
  10349. æD struct DBAsyncParamBlockRec {
  10350.     ProcPtr completionProc; /* pointer to completion routine */
  10351.     OSErr result; /* result of call */
  10352.     long userRef; /* for application's use */
  10353.     long ddevRef; /* for ddev's use */
  10354.     long reserved; /* for internal use */
  10355. };
  10356.  
  10357. typedef struct DBAsyncParamBlockRec DBAsyncParamBlockRec;
  10358. typedef DBAsyncParamBlockRec *DBAsyncParmBlkPtr;
  10359.  
  10360. /*  structure for resource list in QueryRecord 
  10361.  
  10362.  */
  10363. æC 
  10364.  
  10365. æKY ResListElem
  10366. ResListHandle
  10367. æFc DatabaseAccess.h
  10368. æT struct
  10369. æD struct ResListElem {
  10370.     ResType theType; /* resource type */
  10371.     short id; /* resource id */
  10372. };
  10373.  
  10374. typedef struct ResListElem ResListElem;
  10375. /*  structure for query list in QueryRecord  */
  10376. æC 
  10377.  
  10378. æKY QueryRecord
  10379. QueryPtr
  10380. QueryHandle
  10381. æFc DatabaseAccess.h
  10382. æT struct
  10383. æD struct QueryRecord {
  10384.     Short version; /* version */
  10385.     Short id; /* id of 'qrsc' this came from */
  10386.     Handle queryProc; /* handle to query def proc */
  10387.     Str63 ddevName; /* ddev name */
  10388.     Str255 host; /* host */
  10389.     Str255 user; /* user */
  10390.     Str255 password; /* password */
  10391.     Str255 connStr; /* connection string */
  10392.     Short currQuery; /* current query */
  10393.     Short numQueries; /* number of queries in queryList */
  10394.     QueryListHandle queryList; /* handle to list of queries */
  10395.     Short numRes; /* number of resources in resList */
  10396.     ResListHandle resList; /* handle to list of other resources */
  10397.     Handle dataHandle; /* data used by query def proc */
  10398.     long refCon; /* query's reference value */
  10399. };
  10400.  
  10401. typedef struct QueryRecord QueryRecord;
  10402. typedef QueryRecord *QueryPtr, **QueryHandle;
  10403.  
  10404. /*  structure of column types array in ResultsRecord  */
  10405. æC 
  10406.  
  10407. æKY DBColInfoRecord
  10408. æFc DatabaseAccess.h
  10409. æT struct
  10410. æD struct DBColInfoRecord {
  10411.     short len;
  10412.     short places;
  10413.     short flags;
  10414. };
  10415.  
  10416. typedef struct DBColInfoRecord DBColInfoRecord;
  10417. æC 
  10418.  
  10419. æKY ResultsRecord
  10420. æFc DatabaseAccess.h
  10421. æT struct
  10422. æD struct ResultsRecord {
  10423.     Short numRows; /* number of rows in result */
  10424.     Short numCols; /* number of colums per row */
  10425.     Handle colTypes; /* data type array*/
  10426.     Handle colData; /* actual results */
  10427.     Handle colInfo; /* DBColInfoRecord array */
  10428. };
  10429.  
  10430. typedef struct ResultsRecord ResultsRecord;
  10431. æC 
  10432.  
  10433. æKY InitDBPack
  10434. æFc DatabaseAccess.h
  10435. æT Function
  10436. æTN A82F
  10437. æD pascal OSErr InitDBPack(void)
  10438.     = {0x3F3C,0x0004,0x303C,0x0100,0xA82F}; 
  10439. æDT OSErr myVariable = InitDBPack()(void);
  10440. æC 
  10441. You must call the InitDBPack function before you call any other Database Access
  10442. Manager routines. You must call the QuitDBPack function when you are finished
  10443. using the Database Access Manager.
  10444.  
  10445. The InitDBPack function causes the Package Manager to load the Database Access
  10446. Manager into memory, if it has not already done so, and increments the Database
  10447. Access Manager use counter. The use counter prevents any application from
  10448. removing the Database Access Manager from memory while another application is
  10449. using it.  
  10450.  
  10451. The interface routine that implements the InitDBPack function includes a version
  10452. number for the Database Access Manager. If the package is a different version
  10453. than specified by the interface routine, then the InitDBPack function returns
  10454. the rcDBWrongVersion result code.
  10455.  
  10456. Result codes
  10457. noErr                0  No error
  10458. rcDBWrongVersion  –814  Wrong version number
  10459.  
  10460. æKY QuitDBPack
  10461. æFc DatabaseAccess.h
  10462. æT Function
  10463. æTN A82F
  10464. æD pascal OSErr QuitDBPack(void)
  10465.     = {0x303C,0x0001,0xA82F}; 
  10466. æDT OSErr myVariable = QuitDBPack()(void);
  10467. æC 
  10468. The QuitDBPack function decrements the Database Access Manager use counter. When
  10469. this counter equals 0, the QuitDBPack function removes the Database Access
  10470. Manager package from memory. Call this routine when your application is
  10471. terminating or when you are finished using the Database Access Manager. The use
  10472. counter prevents the QuitDBPack function from removing the Database Access
  10473. Manager from memory while any application is still using it.
  10474.  
  10475. Result codes
  10476. noErr                 0  No error
  10477. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  10478.  
  10479. æKY DBInit
  10480. æFc DatabaseAccess.h
  10481. æT Function
  10482. æTN A82F
  10483. æD pascal OSErr DBInit(long *sessID,const Str63 ddevName,const Str255 host,
  10484.     const Str255 user,const Str255 passwd,const Str255 connStr,DBAsyncParmBlkPtr asyncPB)
  10485.     = {0x303C,0x0E02,0xA82F}; 
  10486. æDT OSErr myVariable = DBInit((long *) sessID,(const Str63) ddevName,(const Str255) host,(
  10487.     const) Str255 user,(const Str255) passwd,(const Str255) connStr,(DBAsyncParmBlkPtr) asyncPB);
  10488. æC 
  10489. The DBInit function initiates a session with a remote database server. You must
  10490. initiate a session before you call any Database Access Manager function that
  10491. requires a session ID as an input parameter. If the DBInit function returns a
  10492. nonzero session ID, you must call the DBEnd function to terminate the session,
  10493. even if the DBInit function also returns a result code other than noErr.
  10494.  
  10495. Because the high-level function DBStartQuery can call the DBInit function, if
  10496. you have called the DBStartQuery function, you do not have to call the DBInit
  10497. function. 
  10498.  
  10499. The DBInit function returns the session ID in the sessID parameter. This session
  10500. ID is unique; no other current session, for any database extension, has the same
  10501. session ID. You must specify the session ID any time you want to send data to or
  10502. retrieve data from this session. Depending on the database extension you are
  10503. using, the DBInit function might return a session ID of 0 if it fails to
  10504. initiate a session, or it might return a nonzero session ID and a result code
  10505. other than noErr. In the latter case, you can pass the session ID to the
  10506. DBGetErr function to determine the cause of the error.
  10507.  
  10508. The ddevName parameter is a string of no more than 63 characters that specifies
  10509. the name of the database extension. The name of the database extension is
  10510. contained in the database extension file in a resource of type 'STR ' with an ID
  10511. of 128. For the CL/1 database extension provided by Apple , for example, this
  10512. string is “CL/1”.
  10513.  
  10514. The host parameter specifies the name of the remote system on which the database
  10515. server is located. This name depends on the manner in which the database
  10516. extension establishes communication with the remote database server and on how
  10517. the system administrator has set up the computer system.
  10518.  
  10519. The user parameter specifies the name of the user, and the password parameter
  10520. specifies the password associated with the user name.
  10521.  
  10522. The connStr parameter is a connection string that is passed to the database
  10523. server, which might pass it on to the database management software on the remote
  10524. computer. This string is necessary in some systems to complete log-on
  10525. procedures. 
  10526. The asyncPB parameter is a pointer to the asynchronous parameter block. If you
  10527. do not want to call the function asynchronously, set this parameter to NIL.
  10528.  
  10529. Result codes
  10530. noErr                 0  No error
  10531. rcDBError          –802  Error initiating session
  10532. rcDBBadDDev        –809  Couldn’t find specified database extension or 
  10533.                          trouble opening ddev file
  10534. rcDBAsyncNotSupp   –811  Asynchronous calls are not supported by 
  10535.                          database extension
  10536. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  10537.  
  10538. æKY DBEnd
  10539. æFc DatabaseAccess.h
  10540. æT Function
  10541. æTN A82F
  10542. æD pascal OSErr DBEnd(long sessID,DBAsyncParmBlkPtr asyncPB)
  10543.     = {0x303C,0x0403,0xA82F}; 
  10544. æDT OSErr myVariable = DBEnd((long) sessID,(DBAsyncParmBlkPtr) asyncPB);
  10545. æC 
  10546. The DBEnd function terminates a session with a remote database server and
  10547. terminates the network connection between the application and the remote
  10548. computer. You must call the DBEnd function to terminate a session.
  10549.  
  10550. The sessID parameter is the session ID that was returned by the DBInit function.
  10551.  
  10552. The asyncPB parameter is a pointer to the asynchronous parameter block. If you
  10553. do not want to call the function asynchronously, set this parameter to NIL.
  10554.  
  10555. Result codes
  10556. noErr                 0  No error
  10557. rcDBError          –802  Error ending session
  10558. rcDBBadSessID      –807  Session ID is invalid
  10559. rcDBAsyncNotSupp   –811  Asynchronous calls are not supported by 
  10560.                          database extension
  10561. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  10562.  
  10563. æKY DBGetConnInfo
  10564. æFc DatabaseAccess.h
  10565. æT Function
  10566. æTN A82F
  10567. æD pascal OSErr DBGetConnInfo(long sessID,Short sessNum,long *returnID,long *version,
  10568.     const Str63 ddevName,const Str255 host,const Str255 user,const Str255 network,
  10569.     const Str255 connStr,long *start,OSErr *state,DBAsyncParmBlkPtr asyncPB)
  10570.     = {0x303C,0x1704,0xA82F}; 
  10571. æDT OSErr myVariable = DBGetConnInfo((long) sessID,(Short) sessNum,(long *) returnID,(long *) version,(
  10572.     const) Str63 ddevName,(const Str255) host,(const Str255) user,(const Str255) network,(
  10573.     const) Str255 connStr,(long *) start,(OSErr *) state,(DBAsyncParmBlkPtr) asyncPB);
  10574. æC 
  10575. The DBGetConnInfo function returns information about the specified session,
  10576. including 
  10577.  
  10578.   •   the version of the database extension
  10579.   •   the name of the remote system on which the session is running
  10580.   •   the user name
  10581.   •   the connection string that was used to establish communication
  10582.   •   the name of the network
  10583.   •   the time at which the session started, in ticks
  10584.   •   the status of the session
  10585.  
  10586. In addition, if you include a nonzero value for the sessID parameter when you
  10587. call the DBGetConnInfo function, the function returns the name of the database
  10588. extension. If you use 0 for the sessID parameter and specify the database
  10589. extension and session number instead, the function returns the session ID.
  10590.  
  10591. You can use this function to get information about a particular session, or you
  10592. can call the function repeatedly, incrementing the session number each time, to
  10593. get information about all of the sessions associated with a particular database
  10594. extension.
  10595.  
  10596. The sessID parameter is the session ID that was returned by the DBInit function.
  10597. The sessNum parameter is the session number of the session about which you want
  10598. information. You can specify either the session ID or the session number when
  10599. you call the DBInit function. If you specify the sessID parameter, use 0 for the
  10600. sessNum parameter. If you specify the sessNum parameter, then use 0 for the
  10601. sessID parameter. If you specify the sessNum parameter, you must specify a value
  10602. for the ddevName parameter as well. If you specify the session number and the
  10603. database extension, then the DBGetConnInfo function returns the session ID in
  10604. the returnedID parameter. 
  10605.  
  10606. The version parameter returns the version number of the database extension that
  10607. is the interface to the remote database server on which this session is running.
  10608.  
  10609. The ddevName parameter specifies the name of the database extension. If you
  10610. specify 0 for the session ID, you must include the name of the database
  10611. extension as well as a session number. If you specify a valid session ID, then
  10612. the DBGetConnInfo function returns the name of the database extension in the
  10613. ddevName parameter. The name of the database extension is included in a 'STR '
  10614. resource in the database extension file with a resource ID of 128.
  10615.  
  10616. The host, user, and connStr parameters are the host, user, and connection
  10617. strings that were used to establish communication with the remote database
  10618. server. The network parameter is the name of the network through which your
  10619. computer is communicating with the remote database server.
  10620.  
  10621. The start parameter is the time, in ticks, at which this session was initiated.
  10622.  
  10623. The state parameter returns one of the following values to provide information
  10624. about the status of the session:
  10625.  
  10626. CONST
  10627. noErr      =    0  ;No error; ready for more text
  10628. rcDBValue  = –801  ;Output data available
  10629. rcDBError  = –802  ;Execution ended in an error
  10630. rcDBExec   = –806  ;Busy; currently executing query
  10631.  
  10632. The asyncPB parameter is a pointer to the asynchronous parameter block. If you
  10633. do not want to call the function asynchronously, set this parameter to NIL.
  10634.  
  10635. Result codes
  10636. noErr                 0  No error
  10637. rcDBBadSessNum     –808  Invalid session number
  10638. rcDBBadSessID      –807  Session ID is invalid or database extension name is 
  10639.                          invalid
  10640. rcDBBadDDev        –809  Couldn’t find specified database extension or 
  10641.                          trouble opening ddev file
  10642. rcDBAsyncNotSupp   –811  Asynchronous calls are not supported by 
  10643.                          database extension
  10644. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  10645.  
  10646. æKY DBGetSessionNum
  10647. æFc DatabaseAccess.h
  10648. æT Function
  10649. æTN A82F
  10650. æD pascal OSErr DBGetSessionNum(long sessID,Short *sessNum,DBAsyncParmBlkPtr asyncPB)
  10651.     = {0x303C,0x0605,0xA82F}; 
  10652. æDT OSErr myVariable = DBGetSessionNum((long) sessID,(Short *) sessNum,(DBAsyncParmBlkPtr) asyncPB);
  10653. æC 
  10654. The DBGetSessionNum function returns the session number of the session you
  10655. specify with the session ID parameter. The session number is unique for a
  10656. particular database extension, but the same session number might be in use for
  10657. different database extensions at the same time.
  10658.  
  10659. The asyncPB parameter is a pointer to the asynchronous parameter block. If you
  10660. do not want to call the function asynchronously, set this parameter to NIL.
  10661.  
  10662. Result codes
  10663. noErr                 0  No error
  10664. rcDBBadSessID      –807  Session ID is invalid
  10665. rcDBAsyncNotSupp   –811  Asynchronous calls are not supported by 
  10666.                          database extension
  10667. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  10668.  
  10669. æKY DBSend
  10670. æFc DatabaseAccess.h
  10671. æT Function
  10672. æTN A82F
  10673. æD pascal OSErr DBSend(long sessID,char *text,Short len,DBAsyncParmBlkPtr asyncPB)
  10674.     = {0x303C,0x0706,0xA82F}; 
  10675. æDT OSErr myVariable = DBSend((long) sessID,(char *) text,(Short) len,(DBAsyncParmBlkPtr) asyncPB);
  10676. æC 
  10677. The DBSend function sends a query or a portion of a query to the remote database
  10678. server. The database server appends this portion of the query to any portion you
  10679. sent previously. Because the Database Access Manager and database server do not
  10680. modify the string you send in any way, they do not insert any delimiter between
  10681. fragments of queries that you send to the database server. If you want a blank
  10682. or a semicolon to be included between query fragments, or if you want to use
  10683. return characters to divide the query into lines of text, you must include them
  10684. in the character string that you send with this function. 
  10685.  
  10686. The database server does not execute the query until you call the DBExec
  10687. function.
  10688.  
  10689. The sessID parameter is the session ID that was returned by the DBInit function.
  10690.  
  10691. The text parameter is a pointer to the query or query fragment that you want to
  10692. send to the database server. The query or query fragment must be a character
  10693. string. The len parameter specifies the length of the character string. If the
  10694. len parameter has a value of –1, then the character string is assumed to be 
  10695. “NULL terminated” (that is, the string ends with a NULL byte); otherwise, the
  10696. len parameter specifies the number of bytes in the string.
  10697.  
  10698. The asyncPB parameter is a pointer to the asynchronous parameter block. If you
  10699. do not want to call the function asynchronously, set this parameter to NIL.
  10700.  
  10701. Result codes
  10702. noErr                 0  No error
  10703. rcDBError          –802  Error trying to send text
  10704. rcDBBadSessID      –807  Session ID is invalid
  10705. rcDBAsyncNotSupp   –811  Asynchronous calls are not supported by 
  10706.                          database extension
  10707. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  10708.  
  10709. æKY DBSendItem
  10710. æFc DatabaseAccess.h
  10711. æT Function
  10712. æTN A82F
  10713. æD pascal OSErr DBSendItem(long sessID,char dataType,Short len,Short places,
  10714.     Short flags,Ptr buffer,DBAsyncParmBlkPtr asyncPB)
  10715.     = {0x303C,0x0B07,0xA82F}; 
  10716. æDT OSErr myVariable = DBSendItem((long) sessID,(char) dataType,(Short) len,(Short) places,()
  10717.     Short flags,(Ptr) buffer,(DBAsyncParmBlkPtr) asyncPB);
  10718. æC 
  10719. The DBSendItem function sends a single data item to the remote database server.
  10720. You can use this function to send to the database server the data that you wish
  10721. to include in a query. The database extension or the database server (depending
  10722. on how the system is implemented) converts the data item to a character string
  10723. and appends it to the query, just as a query program fragment is appended to the
  10724. query by the DBSend function. The query is not executed until you call the
  10725. DBExec function.
  10726.  
  10727. The sessID parameter is the session ID that was returned by the DBInit function.
  10728.  
  10729. The dataType, len, and places parameters specify the data type, length, and
  10730. number of decimal places for the data item that you are sending to the remote
  10731. database server. The database extension and database server ignore the len
  10732. parameter if the data type has an implied length. The database extension and
  10733. database server ignore the places parameter for all values of the dataType
  10734. parameter except typeDecimal and typeMoney. Data types are discussed in “Getting
  10735. Query Results” earlier in this chapter.
  10736.  
  10737. The buffer parameter is a pointer to the memory location of the data item that
  10738. you want to send. When you use the DBSendItem function to send an item of data
  10739. to a database server, the database extension and database server format the data
  10740. according to the data type, length, and decimal places you specified, converts
  10741. it to a character string, and appends the data to the query. 
  10742.  
  10743. Set the flags parameter to 0. There are no flags currently defined for the
  10744. DBSendItem function. 
  10745.  
  10746. The asyncPB parameter is a pointer to the asynchronous parameter block. If you
  10747. do not want to call the function asynchronously, set this parameter to NIL.
  10748.  
  10749. Result codes
  10750. noErr                 0  No error
  10751. rcDBError          –802  Error trying to send item
  10752. rcDBBadSessID      –807  Session ID is invalid
  10753. rcDBAsyncNotSupp   –811  Asynchronous calls are not supported by 
  10754.                          database extension
  10755. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  10756.  
  10757. æKY DBExec
  10758. æFc DatabaseAccess.h
  10759. æT Function
  10760. æTN A82F
  10761. æD pascal OSErr DBExec(long sessID,DBAsyncParmBlkPtr asyncPB)
  10762.     = {0x303C,0x0408,0xA82F}; 
  10763. æDT OSErr myVariable = DBExec((long) sessID,(DBAsyncParmBlkPtr) asyncPB);
  10764. æC 
  10765. The DBExec function initiates execution of a query that you have sent to the
  10766. remote database server. Use the DBSend and DBSendItem functions to send a query
  10767. to the database server. Use the DBState function to determine the status of a
  10768. query after you have initiated execution.
  10769.  
  10770. The sessID parameter is the session ID that was returned by the DBInit function.
  10771.  
  10772. The asyncPB parameter is a pointer to the asynchronous parameter block. If you
  10773. do not want to call the function asynchronously, set this parameter to NIL.
  10774.  
  10775. Result codes
  10776. noErr                 0  Execution has begun
  10777. rcDBError          –802  Error trying to begin execution
  10778. rcDBBadSessID      –807  Session ID is invalid
  10779. rcDBAsyncNotSupp   –811  Asynchronous calls are not supported by 
  10780.                          database extension
  10781. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  10782.  
  10783. æKY DBState
  10784. æFc DatabaseAccess.h
  10785. æT Function
  10786. æTN A82F
  10787. æD pascal OSErr DBState(long sessID,DBAsyncParmBlkPtr asyncPB)
  10788.     = {0x303C,0x0409,0xA82F}; 
  10789. æDT OSErr myVariable = DBState((long) sessID,(DBAsyncParmBlkPtr) asyncPB);
  10790. æC 
  10791. The result code returned by the DBState function indicates the status of the
  10792. remote database server. You can use this function to determine whether the
  10793. database server has successfully executed a query and whether it has data
  10794. available for you to retrieve. 
  10795.  
  10796. The sessID parameter is the session ID that was returned by the DBInit function.
  10797.  
  10798. The asyncPB parameter is a pointer to the asynchronous parameter block. If you
  10799. do not want to call the function asynchronously, set this parameter to NIL.
  10800.  
  10801. Result codes
  10802. noErr                 0  No error; ready for more text
  10803. rcDBValue          –801  Output data available
  10804. rcDBError          –802  Execution ended in an error
  10805. rcDBExec           –806  Currently executing query
  10806. rcDBBadSessID      –807  Session ID is invalid
  10807. rcDBAsyncNotSupp   –811  Asynchronous calls are not supported by
  10808.                          database extension
  10809. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  10810.  
  10811. æKY DBGetErr
  10812. æFc DatabaseAccess.h
  10813. æT Function
  10814. æTN A82F
  10815. æD pascal OSErr DBGetErr(long sessID,long *err1,long *err2,const Str255 item1,
  10816.     const Str255 item2,const Str255 errorMsg,DBAsyncParmBlkPtr asyncPB)
  10817.     = {0x303C,0x0E0A,0xA82F}; 
  10818. æDT OSErr myVariable = DBGetErr((long) sessID,(long *) err1,(long *) err2,(const Str255) item1,(
  10819.     const) Str255 item2,(const Str255) errorMsg,(DBAsyncParmBlkPtr) asyncPB);
  10820. æC 
  10821. The DBGetErr function retrieves error codes and error messages from a remote
  10822. database server. You can use this function to obtain information when a
  10823. low-level function returns the result code rcDBError. If the DBState function
  10824. returns the rcDBError result code, indicating that execution of a query ended in
  10825. an error, the error information can help you debug the query. The meaning of
  10826. each error code and error message returned by this function depends on the
  10827. database server with which you are communicating; see the documentation for that
  10828. database server for more information.
  10829.  
  10830. The sessID parameter is the session ID that was returned by the DBInit function.
  10831.  
  10832. The err1 and err2 parameters return the primary and secondary error codes. The
  10833. item1 and item2 parameters return strings that describe the objects of the error
  10834. message. The errorMsg parameter returns the error message.
  10835.  
  10836. The asyncPB parameter is a pointer to the asynchronous parameter block. If you
  10837. do not want to call the function asynchronously, set this parameter to NIL.
  10838.  
  10839. Result codes
  10840. noErr                 0  No error
  10841. rcDBError          –802  Error retrieving error information
  10842. rcDBBadSessID      –807  Session ID is invalid
  10843. rcDBAsyncNotSupp   –811  Asynchronous calls are not supported by
  10844.                          database extension
  10845. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  10846.  
  10847. æKY DBBreak
  10848. æFc DatabaseAccess.h
  10849. æT Function
  10850. æTN A82F
  10851. æD pascal OSErr DBBreak(long sessID,Boolean abort,DBAsyncParmBlkPtr asyncPB)
  10852.     = {0x303C,0x050B,0xA82F}; 
  10853. æDT OSErr myVariable = DBBreak((long) sessID,(Boolean) abort,(DBAsyncParmBlkPtr) asyncPB);
  10854. æC 
  10855. The DBBreak function can halt execution of a query and reinitialize the remote
  10856. database server, or it can unconditionally terminate a session with a database
  10857. server. You can use this function to cancel a query if you determine that it is
  10858. taking too long to complete execution, for example.
  10859.  
  10860. The sessID parameter is the session ID that was returned by the DBInit function.
  10861.  
  10862. If the abort parameter is TRUE (nonzero), the database server halts any query
  10863. that is executing and terminates the current session. If the abort parameter is
  10864. FALSE (0), the database server halts any query that is executing and
  10865. reinitializes itself.
  10866.  
  10867. The asyncPB parameter is a pointer to the asynchronous parameter block. If you
  10868. do not want to call the function asynchronously, set this parameter to NIL.
  10869.  
  10870. Result codes
  10871. noErr                 0  Execution has begun
  10872. rcDBError          –802  Break or abort attempt was unsuccessful
  10873. rcDBBadSessID      –807  Session ID is invalid
  10874. rcDBAsyncNotSupp   –811  Asynchronous calls are not supported by 
  10875.                          database extension
  10876. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  10877.  
  10878. æKY DBGetItem
  10879. æFc DatabaseAccess.h
  10880. æT Function
  10881. æTN A82F
  10882. æD pascal OSErr DBGetItem(long sessID,long timeout,char *dataType,sort *len,
  10883.     Short *places,Short *flags,Ptr buffer,DBAsyncParmBlkPtr asyncPB)
  10884.     = {0x303C,0x100C,0xA82F}; 
  10885. æDT OSErr myVariable = DBGetItem((long) sessID,(long) timeout,(char *) dataType,(sort *) len,(
  10886.     Short) * places,(Short *) flags,(Ptr) buffer,(DBAsyncParmBlkPtr) asyncPB);
  10887. æC 
  10888. The DBGetItem function retrieves the next data item from the database server.
  10889. You can also use this function to obtain information about the next data item
  10890. without retrieving the data. You can use the DBGetItem function after you have
  10891. executed a query and the DBState function has returned the result code
  10892. rcDBValue, indicating that data is available. You can repeat the DBGetItem
  10893. function as many times as is necessary to retrieve all of the data returned by
  10894. the database in response to a query.
  10895.  
  10896. The sessID parameter is the session ID that was returned by the DBInit function.
  10897.  
  10898. You can use the timeout parameter to specify the maximum amount of time that the
  10899. database extension should wait to receive results from the database server
  10900. before canceling the function. Specify the timeout parameter in sixtieths of a
  10901. second. To disable the timeout feature, set the timeout parameter to the value
  10902. kDBWaitForever. If the timeout period expires, the DBGetItem function returns
  10903. the result code rcDBBreak. The DBGetItem function ignores the timeout parameter
  10904. if you call the function asynchronously. 
  10905.  
  10906. One use for the timeout parameter is to call the DBGetItem function periodically
  10907. with a short value set for this parameter in order to return control to your
  10908. application while a query is executing. Your application can then retrieve the
  10909. next data item as soon as execution of the query is complete without having to
  10910. call the DBState function to determine when data is available.
  10911.  
  10912. You can set the dataType parameter to specify the data type that you expect the
  10913. next data item to be. If the item is not of the expected data type, the database
  10914. extension returns the rcDBBadType result code. If you want to retrieve the next
  10915. data item regardless of type, set the dataType parameter to the value
  10916. typeAnyType. To skip the next data item, set the dataType parameter to the value
  10917. typeDiscard. The database server sets the dataType parameter to the actual type
  10918. of the data item when it retrieves the data item or returns information about
  10919. the data item. Data types are discussed in “Getting Query Results” earlier in
  10920. this chapter.
  10921.  
  10922. Set the len parameter to the length of the data buffer pointed to by the buffer
  10923. parameter. If you use the DBGetItem function to obtain information only (by
  10924. setting the buffer parameter to NIL), then the database server ignores the len
  10925. parameter. The database server sets the len parameter to the actual length of
  10926. the data item when it retrieves the data item or returns information about the
  10927. data item.
  10928.  
  10929. The database server returns in the places parameter the number of decimal places
  10930. in data items of types typeMoney and typeDecimal. For all other data types, the
  10931. database server returns 0 for the places parameter.
  10932.  
  10933. The buffer parameter is a pointer to the location where you want the retrieved
  10934. data item to be stored. You must ensure that the location you specify contains
  10935. enough space for the data item that will be returned. To determine the data
  10936. type, length, and number of decimal places of the next data item without
  10937. retrieving it, specify NIL for the buffer parameter. 
  10938.  
  10939. If the flags parameter is set to kDBLastColFlag (that is, the least significant
  10940. bit is set to 1), the data item is in the last column of the row. 
  10941. The asyncPB parameter is a pointer to the asynchronous parameter block. If you
  10942. do not want to call the function asynchronously, set this parameter to NIL.
  10943.  
  10944. Result codes
  10945. noErr                 0  No error; no next data item
  10946. rcDBNull           –800  The data item was NULL
  10947. rcDBValue          –801  A nonzero data item was successfully retrieved
  10948. rcDBError          –802  Execution ended in an error
  10949. rcDBBadType        –803  Next data item not of requested data type
  10950. rcDBBreak          –805  Timed out
  10951. rcDBBadSessID      –807  Session ID is invalid
  10952. rcDBAsyncNotSupp   –811  Asynchronous calls are not supported by 
  10953.                          database extension
  10954. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  10955.  
  10956. æKY DBUnGetItem
  10957. æFc DatabaseAccess.h
  10958. æT Function
  10959. æTN A82F
  10960. æD pascal OSErr DBUnGetItem(long sessID,DBAsyncParmBlkPtr asyncPB)
  10961.     = {0x303C,0x040D,0xA82F}; 
  10962. æDT OSErr myVariable = DBUnGetItem((long) sessID,(DBAsyncParmBlkPtr) asyncPB);
  10963. æC 
  10964. The DBUnGetItem function reverses the effect of the last call to the DBGetItem
  10965. function, in the sense that the next time you call the DBGetItem function it
  10966. retrieves the same item a second time. It does not remove the just-retrieved
  10967. data item from the input buffer. The DBUnGetItem function can reverse the effect
  10968. of only one call to the DBGetItem function; you cannot use it to step back
  10969. through several previously retrieved data items. 
  10970.  
  10971. The sessID parameter is the session ID that was returned by the DBInit function.
  10972.  
  10973. The asyncPB parameter is a pointer to the asynchronous parameter block. If you
  10974. do not want to call the function asynchronously, set this parameter to NIL.
  10975.  
  10976. Result codes
  10977. noErr                 0  No error
  10978. rcDBError          –802  Error executing function
  10979. rcDBBadSessID      –807  Session ID is invalid
  10980. rcDBAsyncNotSupp   –811  Asynchronous calls are not supported by 
  10981.                          database extension
  10982. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  10983.  
  10984. æKY DBKill
  10985. æFc DatabaseAccess.h
  10986. æT Function
  10987. æTN A82F
  10988. æD pascal OSErr DBKill(DBAsyncParmBlkPtr asyncPB)
  10989.     = {0x303C,0x020E,0xA82F}; 
  10990. æDT OSErr myVariable = DBKill((DBAsyncParmBlkPtr) asyncPB);
  10991. æC 
  10992. The DBKill function cancels the execution of the asynchronous call specified by
  10993. the asyncPB parameter.
  10994.  
  10995. The asyncPB parameter is a pointer to the asynchronous parameter block.
  10996.  
  10997. Result codes
  10998. noErr                 0  Asynchronous routine canceled successfully
  10999. rcDBError          –802  Error canceling routine
  11000. rcDBBadAsynchPB    –812  Invalid parameter block specified
  11001. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  11002.  
  11003. æKY DBGetNewQuery
  11004. æFc DatabaseAccess.h
  11005. æT Function
  11006. æTN A82F
  11007. æD pascal OSErr DBGetNewQuery(Short queryID,QueryHandle *qeury)
  11008.     = {0x303C,0x030F,0xA82F}; 
  11009. æDT OSErr myVariable = DBGetNewQuery((Short) queryID,(QueryHandle *) qeury);
  11010. æC 
  11011. The DBGetNewQuery function creates a query record from the 'qrsc' resource with
  11012. the resource ID you specify in the queryID parameter. The resource file that
  11013. contains the 'qrsc' resource must remain open until after the DBStartQuery
  11014. function has completed execution. If you do not already know the resource ID of
  11015. the 'qrsc' resource (for example, if you call the SFGetFile procedure to let the
  11016. user select the query document), you can use Resource Manager routines to
  11017. determine the resource ID. The SFGetFile procedure is described in the Standard
  11018. File Package chapter of Volume I and the Resource Manager is described in Volume
  11019. Chapter 5.
  11020.  
  11021. The queryID parameter specifies the resource ID of the 'qrsc' resource that you
  11022. want to use. The query parameter returns a handle to the query record.
  11023.  
  11024. Result code
  11025. noErr                 0  Query record built successfully
  11026. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  11027.  
  11028. æKY DBDisposeQuery
  11029. æFc DatabaseAccess.h
  11030. æT Function
  11031. æTN A82F
  11032. æD 
  11033. pascal OSErr DBDisposeQuery(QueryHandle query)
  11034.     = {0x303C,0x0210,0xA82F}; 
  11035. æDT OSErr myVariable = DBDisposeQuery((QueryHandle) query);
  11036. æC 
  11037. The DBDisposeQuery function disposes of a query record and frees all the memory
  11038. that the Database Access Manager allocated when it created the query record. You
  11039. should call this function after you are finished using a query record.
  11040.  
  11041. The query parameter is a handle to the query record.
  11042.  
  11043. Result code
  11044. noErr                 0  Query record disposed of successfully
  11045. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  11046.  
  11047. æKY DBStartQuery
  11048. æFc DatabaseAccess.h
  11049. æT Function
  11050. æTN A82F
  11051. æD pascal OSErr DBStartQuery(long *sessID,QueryHandle query,ProcPtr statusProc,
  11052.     DBAsyncParmBlkPtr asyncPB)
  11053.     = {0x303C,0x0811,0xA82F}; 
  11054. æDT OSErr myVariable = DBStartQuery((long *) sessID,(QueryHandle) query,(ProcPtr) statusProc,()
  11055.     DBAsyncParmBlkPtr asyncPB);
  11056. æC 
  11057. The DBStartQuery function performs the following tasks, in the order specified:
  11058.  
  11059. 1.  It calls the query definition function (if any) pointed to by the query
  11060. record. The query definition function modifies the query record and the query,
  11061. usually by asking the user for input. The query definition function can display
  11062. a dialog box that gives the user the option of canceling the query; if the user
  11063. does cancel the query, the DBStartQuery function returns the userCanceledErr
  11064. result code.
  11065.  
  11066. 2.  If you specify a nonzero value for the statusProc parameter, the
  11067. DBStartQuery function calls your status routine with the value kDBUpdateWind in
  11068. the message parameter so that your application can update its windows.
  11069.  
  11070. 3.  If you specify a nonzero value for the statusProc parameter, the
  11071. DBStartQuery function calls your status routine with the value kDBAboutToInit in
  11072. the message parameter so that your application can display a dialog box
  11073. informing the user that a database session is about to be established, and
  11074. giving the user the option of canceling execution of the function.
  11075.  
  11076. 4.  If the sessID parameter is 0, the DBStartQuery function calls the DBInit
  11077. function to establish a database session, and returns a session ID. 
  11078.  
  11079. 5.  If you specify a nonzero value for the statusProc parameter and the
  11080. DBStartQuery function called the DBInit function, the DBStartQuery function
  11081. calls your status routine with the value kDBInitComplete in the message
  11082. parameter and the result of the DBInit function in the result parameter.
  11083.  
  11084. 6.  The DBStartQuery function calls the DBSend function to send the query to the
  11085. remote database server.
  11086.  
  11087. 7.  If you specify a nonzero value for the statusProc parameter, the
  11088. DBStartQuery function calls your status routine with the value kDBSendComplete
  11089. in the message parameter and the result of the DBSend function in the result
  11090. parameter.
  11091.  
  11092. 8.  The DBStartQuery function calls the DBExec function to execute the query.
  11093.  
  11094. 9.  If you specify a nonzero value for the statusProc parameter, the
  11095. DBStartQuery function calls your status routine with the value kDBExecComplete
  11096. in the message parameter and the result of the DBExec function in the result
  11097. parameter.
  11098.  
  11099. 10.  If you specify a nonzero value for the statusProc parameter, the
  11100. DBStartQuery function calls your status routine with the value
  11101. kDBStartQueryComplete in the message parameter and the result of the
  11102. DBStartQuery function in the result parameter.
  11103.  
  11104. You can use the sessID parameter to specify a session ID if your application or
  11105. another application has already established a session with the database server.
  11106. If you specify NIL for this parameter, then the DBStartQuery function
  11107. establishes a session and returns the session ID in the sessID parameter.
  11108.  
  11109. You use the query parameter to specify a handle to a query record. 
  11110. You can use the statusProc pointer to specify a pointer to a status routine that
  11111. your application can use to update its windows after the query definition
  11112. function has completed execution. If you specify NIL for this parameter, the
  11113. DBStartQuery function does not attempt to update your application’s windows. The
  11114. DBStartQuery function also calls your status routine before it initiates a
  11115. database session, after it calls the DBInit function, after it calls the DBSend
  11116. function, and after it calls the DBExec function. Status routines are discussed
  11117. in “Writing a Status Routine for High-Level Functions” earlier in this chapter.
  11118.  
  11119. If you specify a pointer to an asynchronous parameter block in the asyncPB
  11120. parameter, the DBStartQuery function calls the DBInit, DBSend, and DBExec
  11121. functions asynchronously. As soon as the DBInit function has started execution,
  11122. it returns control to your application. Your application must then call the
  11123. WaitNextEvent routine periodically to allow these asynchronous routines to run,
  11124. and it must check the result field of the asynchronous parameter block to
  11125. determine when each routine has completed execution.
  11126.  
  11127. Result codes
  11128. noErr                 0  No error
  11129. userCanceledErr    –128  User canceled the query 
  11130. rcDBError          –802  Error initiating session, sending text, or executing 
  11131.                          query
  11132. rcDBBadDDev        –809  Couldn’t find the specified database extension, or
  11133.                          error occurred in opening database extension   
  11134. rcDBAsyncNotSupp   –811  The database extension does not support asynchronous
  11135.                          calls
  11136. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  11137.  
  11138. æKY DBGetQueryResults
  11139. æFc DatabaseAccess.h
  11140. æT Function
  11141. æTN A82F
  11142. æD pascal OSErr DBGetQueryResults(long sessID,ResultsRecord *results,long timeout,
  11143.     ProcPtr statusProc,DBAsyncParmBlkPtr asyncPB)
  11144.     = {0x303C,0x0A12,0xA82F}; 
  11145. æDT OSErr myVariable = DBGetQueryResults((long) sessID,(ResultsRecord *) results,(long) timeout,()
  11146.     ProcPtr statusProc,(DBAsyncParmBlkPtr) asyncPB);
  11147. æC 
  11148. The DBGetQueryResults function retrieves the results returned by a query and
  11149. places them in memory. If there is sufficient memory available, this function
  11150. retrieves all of the results at once. If the DBGetQueryResults function runs out
  11151. of memory, it places as much data as possible in memory, up to the last whole
  11152. row. You can then make more memory available and call the DBGetQueryResults
  11153. function again to retrieve more data. 
  11154.  
  11155. The DBGetQueryResults function can be used to retrieve the results of any query,
  11156. not only queries sent and executed by the DBStartQuery function.
  11157.  
  11158. The sessID parameter specifies the ID of the session from which you wish to
  11159. retrieve results. 
  11160. The results parameter is the results record, which contains a handle to the
  11161. retrieved data. Results records are described in “Getting Query Results” earlier
  11162. in this chapter.
  11163.  
  11164. The timeout parameter specifies the value that he DBGetQueryResults uses for the
  11165. timeout parameter each time it calls the DBGetItem function. The timeout
  11166. parameter specifies the maximum amount of time that the database extension
  11167. should wait to receive results from the database server before canceling the
  11168. DBGetItem function. Specify the timeout parameter in sixtieths of a second. To
  11169. disable the timeout feature, set the timeout parameter to the value
  11170. kDBWaitForever. This parameter is ignored if you specify a nonzero value for the
  11171. asyncPB parameter.
  11172.  
  11173. You can use the statusProc pointer to specify a pointer to a status routine that
  11174. you provide. The DBGetQueryResults function calls your status routine after it
  11175. calls the DBGetItem function to retrieve a data item. When it calls the status
  11176. routine, the DBGetQueryResults function provides the results of the DBGetItem
  11177. function, the data type, the data length, number of decimal places, and flags
  11178. associated with the data item, and a pointer to the data item. Status routines
  11179. are discussed in “Writing a Status Routine For High-Level Functions” earlier in
  11180. this chapter.
  11181.  
  11182. If you specify a pointer to an asynchronous parameter block in the asyncPB
  11183. parameter, the DBGetQueryResults function calls the DBGetItem function
  11184. asynchronously for each data item. As soon as the DBGetItem function has started
  11185. execution, it returns control to your application. Your application must then
  11186. call the WaitNextEvent routine periodically to allow this asynchronous routine
  11187. to run, and it must check the result field of the asynchronous parameter block
  11188. to determine when the routine has completed execution.
  11189.  
  11190. Result codes
  11191. noErr                 0  Query execution successful; no results returned
  11192. userCanceledErr    –128  Function canceled by status routine
  11193. rcDBValue          –801  Data available 
  11194. rcDBError          –802  Query execution ended in an error
  11195. rcDBBreak          –805  Function timed out
  11196. rcDBExec           –806  Query currently executing 
  11197. rcDBBadSessID      –807  Session ID is invalid
  11198. rcDBAsyncNotSupp   –811  The database extension does not support 
  11199.                          asynchronous calls
  11200. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  11201.  
  11202. æKY DBResultsToText
  11203. æFc DatabaseAccess.h
  11204. æT Function
  11205. æTN A82F
  11206. æD pascal OSErr DBResultsToText(ResultsRecord *results,Handle *theText)
  11207.     = {0x303C,0x0413,0xA82F}; 
  11208. æDT OSErr myVariable = DBResultsToText((ResultsRecord *) results,(Handle *) theText);
  11209. æC 
  11210. The DBResultsToText function calls result handlers to convert to text the data
  11211. retrieved by the DBGetQueryResults function. Result handlers are described in 
  11212. “Converting Query Results to Text” earlier in this chapter.
  11213.  
  11214. The results parameter is the results record returned by the DBGetQueryResults
  11215. function. The parameter theText contains a handle to the converted text. This
  11216. handle is allocated by the Database Access Manager.
  11217.  
  11218. Result code
  11219. noErr                 0  No error
  11220. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  11221.  
  11222. æKY DBInstallResultHandler
  11223. æFc DatabaseAccess.h
  11224. æT Function
  11225. æTN A82F
  11226. æD pascal OSErr DBInstallResultHandler(char dataType,ProcPtr theHandler,Boolean isSysHandler)
  11227.     = {0x303C,0x0514,0xA82F}; 
  11228. æDT OSErr myVariable = DBInstallResultHandler((char) dataType,(ProcPtr) theHandler,(Boolean) isSysHandler);
  11229. æC 
  11230. The DBInstallResultHandler function installs a result handler for the data type
  11231. specified by the dataType parameter. The result handler is then used by the
  11232. DBResultsToText function to convert data of the specified type into a character
  11233. string.
  11234.  
  11235. The parameter theHandler is a pointer to the result handler. The isSysHandler
  11236. parameter specifies whether the result handler is an application result
  11237. handler—to be used only when the DBResultsToText function is called by the
  11238. application that installed the result handler—or  a system result handler—to be
  11239. used by every application running on the system.
  11240.  
  11241. When you install an application result handler, it replaces any result handler
  11242. with the same name previously installed by that application. Similarly, when you
  11243. install a system result handler, it replaces any existing system result handler
  11244. with the same name. Before you temporarily replace an existing result handler,
  11245. use the DBGetResultHandler function to obtain a pointer to the present handler,
  11246. and save the present result handler in your application’s private storage. Then
  11247. you can reinstall the original result handler when you are finished using the
  11248. temporary one.
  11249.  
  11250. Because an application result handler is used in preference to a system result
  11251. handler if both are available, you can temporarily replace a system result
  11252. handler for purposes of your application by installing an application result
  11253. handler for the same data type. You can then use the DBRemoveResultHandler
  11254. function to remove the application result handler and return to using the system
  11255. result handler whenever you wish.
  11256.  
  11257. Result code
  11258. noErr                 0  No error
  11259. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  11260.  
  11261. æKY DBRemoveResultHandler
  11262. æFc DatabaseAccess.h
  11263. æT Function
  11264. æTN A82F
  11265. æD pascal OSErr DBRemoveResultHandler(char dataType)
  11266.     = {0x303C,0x0215,0xA82F}; 
  11267. æDT OSErr myVariable = DBRemoveResultHandler((char) dataType);
  11268. æC 
  11269. The DBRemoveResultHandler function removes from memory the application result
  11270. handler for the data type that you specify with the dataType parameter. This
  11271. function cannot remove a system result handler. 
  11272.  
  11273. Result codes
  11274. noErr                 0  No error
  11275. rcDBNoHandler      –813  There is no handler for this data type installed 
  11276.                          for the current application
  11277. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  11278.  
  11279. æKY DBGetResultHandler
  11280. æFc DatabaseAccess.h
  11281. æT Function
  11282. æTN A82F
  11283. æD pascal OSErr DBGetResultHandler(char dataType,ProcPtr *theHandler,Boolean getSysHandler)
  11284.     = {0x303C,0x0516,0xA82F}; 
  11285. æDT OSErr myVariable = DBGetResultHandler((char) dataType,(ProcPtr *) theHandler,(Boolean) getSysHandler);
  11286. æC 
  11287. The DBGetResultHandler function returns a pointer to a result handler for the
  11288. data type specified with the dataType parameter. The pointer is returned in the
  11289. parameter theHandler.
  11290.  
  11291. If you set the isSysHandler parameter to FALSE (0), the function returns a
  11292. pointer to the current application result handler for the specified data type,
  11293. or it returns 0 if there is no application result handler for that data type. If
  11294. you set the isSysHandler parameter to TRUE (nonzero), the function returns a
  11295. pointer to the current system result handler for the specified data type, or it
  11296. returns 0 if there is no system result handler for that data type.
  11297.  
  11298. You can use this function to obtain a pointer to a result handler so that you
  11299. can use it to convert to text  an individual data item retrieved by the
  11300. DBGetItem function. The DBGetQueryResults function automatically converts to
  11301. text all of the data pointed to by the results record.
  11302.  
  11303. Result codes
  11304. noErr                 0  No error
  11305. rcDBNoHandler      –813  There is no handler for this data type installed
  11306. rcDBPackNotInited  –815  The InitDBPack function has not yet been called
  11307.  
  11308.  
  11309. æKY DDEV.h
  11310. æKL 
  11311. DDEVFlags
  11312. DDEVParams
  11313. DDEVParamsPtr
  11314. kAsyncSupported
  11315. kDBBreak
  11316. kDBClose
  11317. kDBEnd
  11318. kDBExec
  11319. kDBGetConnInfo
  11320. kDBGetErr
  11321. kDBGetItem
  11322. kDBGetSessionNum
  11323. kDBIdle
  11324. kDBInit
  11325. kDBKill
  11326. kDBOpen
  11327. kDBSend
  11328. kDBSendItem
  11329. kDBState
  11330. kDBUnGetItem
  11331. kDDEVFlags
  11332. kDDEVID
  11333. kDDEVName
  11334.  
  11335. æKY kDBInit
  11336. æFc DDEV.h
  11337. æT #define
  11338. æD 
  11339. /*  messages for ddev  */
  11340.  
  11341. #define kDBInit 0
  11342. æC 
  11343.  
  11344. æKY kDBEnd
  11345. æFc DDEV.h
  11346. æT #define
  11347. æD #define kDBEnd 1
  11348. æC 
  11349.  
  11350. æKY kDBGetConnInfo
  11351. æFc DDEV.h
  11352. æT #define
  11353. æD #define kDBGetConnInfo 2
  11354. æC 
  11355.  
  11356. æKY kDBGetSessionNum
  11357. æFc DDEV.h
  11358. æT #define
  11359. æD #define kDBGetSessionNum 3
  11360. æC 
  11361.  
  11362. æKY kDBSend
  11363. æFc DDEV.h
  11364. æT #define
  11365. æD #define kDBSend 4
  11366. æC 
  11367.  
  11368. æKY kDBSendItem
  11369. æFc DDEV.h
  11370. æT #define
  11371. æD #define kDBSendItem 5
  11372. æC 
  11373.  
  11374. æKY kDBExec
  11375. æFc DDEV.h
  11376. æT #define
  11377. æD #define kDBExec 6
  11378. æC 
  11379.  
  11380. æKY kDBState
  11381. æFc DDEV.h
  11382. æT #define
  11383. æD #define kDBState 7
  11384. æC 
  11385.  
  11386. æKY kDBGetErr
  11387. æFc DDEV.h
  11388. æT #define
  11389. æD #define kDBGetErr 8
  11390. æC 
  11391.  
  11392. æKY kDBBreak
  11393. æFc DDEV.h
  11394. æT #define
  11395. æD #define kDBBreak 9
  11396. æC 
  11397.  
  11398. æKY kDBGetItem
  11399. æFc DDEV.h
  11400. æT #define
  11401. æD #define kDBGetItem 10
  11402. æC 
  11403.  
  11404. æKY kDBUnGetItem
  11405. æFc DDEV.h
  11406. æT #define
  11407. æD #define kDBUnGetItem 11
  11408. æC 
  11409.  
  11410. æKY kDBKill
  11411. æFc DDEV.h
  11412. æT #define
  11413. æD #define kDBKill 12
  11414. æC 
  11415.  
  11416. æKY kDBOpen
  11417. æFc DDEV.h
  11418. æT #define
  11419. æD #define kDBOpen 100
  11420. æC 
  11421.  
  11422. æKY kDBClose
  11423. æFc DDEV.h
  11424. æT #define
  11425. æD #define kDBClose 101
  11426. æC 
  11427.  
  11428. æKY kDBIdle
  11429. æFc DDEV.h
  11430. æT #define
  11431. æD #define kDBIdle 102
  11432. æC 
  11433.  
  11434. æKY kDDEVName
  11435. æFc DDEV.h
  11436. æT #define
  11437. æD 
  11438. /*  resource IDs of misc. resources  */
  11439.  
  11440. #define kDDEVName 128 /* ID of 'STR ' resource with ddev name */
  11441. æC 
  11442.  
  11443. æKY kDDEVID
  11444. æFc DDEV.h
  11445. æT #define
  11446. æD #define kDDEVID 128 /* ID of 'ddev' resource */
  11447. æC 
  11448.  
  11449. æKY kDDEVFlags
  11450. æFc DDEV.h
  11451. æT #define
  11452. æD #define kDDEVFlags 128 /* ID of 'dflg' resource */
  11453. æC 
  11454.  
  11455. æKY kAsyncSupported
  11456. æFc DDEV.h
  11457. æT #define
  11458. æD #define kAsyncSupported 0x00000001 /* bit for async support */
  11459. æC 
  11460.  
  11461. æKY DDEVFlags
  11462. æFc DDEV.h
  11463. æT struct
  11464. æD struct DDEVFlags {
  11465.     long version; /* always 0 for this release */
  11466.     long flags; /* flags */
  11467. };
  11468.  
  11469. typedef struct DDEVFlags DDEVFlags;
  11470. æC 
  11471.  
  11472. æKY DDEVParams
  11473. DDEVParamsPtr
  11474. æFc DDEV.h
  11475. æT struct
  11476. æD struct DDEVParams {
  11477.     Short message; /* action for ddev */
  11478.     long ddevStorage; /* storage for ddev */
  11479.     DBAsyncParmBlkPtr asyncPB; /* async parameter block pointer */
  11480.     long sessID; /* session ID */
  11481.     long returnedID; /* session ID returned by DBGetConnInfo */
  11482.     long version; /* version returned by DBGetConnInfo */
  11483.     long start; /* start returned by DBGetConnInfo */
  11484.     StringPtr host; /* host for DBInit and DBGetConnInfo */
  11485.     StringPtr user; /* user for DBInit and DBGetConnInfo */
  11486.     StringPtr password; /* password for DBInit and DBGetConnInfo */
  11487.     StringPtr connStr; /* connection string for DBInit and DBGetConnInfo */
  11488.     StringPtr network; /* network for DBInit and DBGetConnInfo */
  11489.     Ptr buffer; /* buffer used in several calls */
  11490.     long err1; /* error 1 for DGGetErr */
  11491.     long err2; /* error 2 for DGGetErr */
  11492.     StringPtr item1; /* item 1 for DGGetErr */
  11493.     StringPtr item2; /* item 2 for DGGetErr */
  11494.     StringPtr errorMsg; /* errorMsg for DGGetErr */
  11495.     long timeout; /* timeout for DGGetItem*/
  11496.     DBType dataType; /* type for several calls */
  11497.     Short sessNum; /* session number for DBGetConnInfo and DBGetSessionNum*/
  11498.     Short state; /* state for DBGetConnInfo */
  11499.     Short len; /* length of buffer */
  11500.     Short places; /* places for DBSendItem and DBGetItem */
  11501.     Short flags; /* flags for DBSendItem and DBGetItem */
  11502.     Boolean abort; /* abort for DBBreak */
  11503. };
  11504.  
  11505. typedef struct DDEVParams DDEVParams;
  11506. typedef DDEVParams *DDEVParamsPtr;
  11507.  
  11508. æC 
  11509.  
  11510.  
  11511. æKY Desk.h
  11512. æKL CloseDeskAcc
  11513. opendeskacc
  11514. OpenDeskAcc
  11515. SystemClick
  11516. SystemEdit
  11517. SystemEvent
  11518. SystemMenu
  11519. SystemTask
  11520.  
  11521. accClear
  11522. accCopy
  11523. accCursor
  11524. accCut
  11525. accEvent
  11526. accMenu
  11527. accPaste
  11528. accRun
  11529. accUndo
  11530. goodbye
  11531.  
  11532. æKY accEvent
  11533. æFc Desk.h
  11534. æT #define
  11535. æD #define accEvent 64
  11536. æC 
  11537.  
  11538. æKY accRun
  11539. æFc Desk.h
  11540. æT #define
  11541. æD #define accRun 65
  11542. æC 
  11543.  
  11544. æKY accCursor
  11545. æFc Desk.h
  11546. æT #define
  11547. æD #define accCursor 66
  11548. æC 
  11549.  
  11550. æKY accMenu
  11551. æFc Desk.h
  11552. æT #define
  11553. æD #define accMenu 67
  11554. æC 
  11555.  
  11556. æKY accUndo
  11557. æFc Desk.h
  11558. æT #define
  11559. æD #define accUndo 68
  11560. æC 
  11561.  
  11562. æKY accCut
  11563. æFc Desk.h
  11564. æT #define
  11565. æD #define accCut 70
  11566. æC 
  11567.  
  11568. æKY accCopy
  11569. æFc Desk.h
  11570. æT #define
  11571. æD #define accCopy 71
  11572. æC 
  11573.  
  11574. æKY accPaste
  11575. æFc Desk.h
  11576. æT #define
  11577. æD #define accPaste 72
  11578. æC 
  11579.  
  11580. æKY accClear
  11581. æFc Desk.h
  11582. æT #define
  11583. æD #define accClear 73
  11584. æC 
  11585.  
  11586. æKY goodbye
  11587. æFc Desk.h
  11588. æT #define
  11589. æD #define goodbye -1 /*goodbye message*/
  11590. æC 
  11591.  
  11592. æKY OpenDeskAcc
  11593. æFc Desk.h
  11594. æT Function
  11595. æTN A9B6
  11596. æD pascal short OpenDeskAcc(const Str255 theAcc)
  11597.     = 0xA9B6; 
  11598. æDT short myVariable = OpenDeskAcc((const Str255) theAcc);
  11599. æMM
  11600. æRI I-440
  11601. æC 
  11602. OpenDeskAcc opens the desk accessory having the given name and displays its window
  11603. (if any) as the active window. The name is the accessory’s resource name, which you
  11604. get from the Apple menu by calling the Menu Manager procedure GetItem. OpenDeskAcc
  11605. calls the Resource Manager to read the desk accessory from the resource file into the
  11606. application heap.
  11607.  
  11608. You should ignore the value returned by OpenDeskAcc. If the desk accessory is successfully
  11609. opened, the function result is its driver reference number. However, if the desk
  11610. accessory can’t be opened, the function result is undefined; the accessory will have
  11611. taken care of informing the user of the problem (such as memory full) and won’t
  11612. display itself.
  11613.  
  11614. Warning:  Early versions of some desk accessories may set the current
  11615.           grafPort to the accessory’s port upon return from OpenDeskAcc.
  11616.           To be safe, you should bracket your call to OpenDeskAcc with
  11617.           calls to the QuickDraw procedures GetPort and SetPort, to save
  11618.           and restore the current port.
  11619.  
  11620. Note:  Programmers concerned about the amount of available memory should
  11621.        be aware that an open desk accessory uses from 1K to 3K bytes of
  11622.        heap space in addition to the space needed for the accessory itself.
  11623.        The desk accessory is responsible for determining whether there is
  11624.        sufficient memory for it to run; this can be done by calling
  11625.        SizeResource followed by ResrvMem.
  11626.  
  11627. æKY CloseDeskAcc
  11628. æFc Desk.h
  11629. æT Function
  11630. æTN A9B7
  11631. æD pascal void CloseDeskAcc(short refNum)
  11632.     = 0xA9B7; 
  11633. æDT CloseDeskAcc((short) refNum);
  11634. æRI I-440
  11635. æC 
  11636. When a system window is active and the user chooses Close from the File menu, call
  11637. CloseDeskAcc to close the desk accessory. RefNum is the driver reference number for
  11638. the desk accessory, which you get from the windowKind field of its window.
  11639.  
  11640. The Desk Manager automatically closes a desk accessory if the user clicks its close
  11641. box. Also, since the application heap is released when the application terminates,
  11642. every desk accessory goes away at that time.
  11643.  
  11644. æKY SystemClick
  11645. æFc Desk.h
  11646. æT Function
  11647. æTN A9B3
  11648. æD pascal void SystemClick(const EventRecord *theEvent,WindowPtr theWindow)
  11649.     = 0xA9B3; 
  11650. æDT SystemClick((const EventRecord *) theEvent,(WindowPtr) theWindow);
  11651. æMM
  11652. æRI I-441, P-35, 182
  11653. æC 
  11654. When a mouse-down event occurs and the Window Manager function FindWindow reports
  11655. that the mouse button was pressed in a system window, the application should call
  11656. SystemClick with the event record and the window pointer. If the given window belongs
  11657. to a desk accessory, SystemClick sees that the event gets handled properly.
  11658.  
  11659. SystemClick determines which part of the desk accessory’s window the mouse button was
  11660. pressed in, and responds accordingly (similar to the way your application responds to
  11661. mouse activities in its own windows).
  11662.  
  11663.   •  If the mouse button was pressed in the content region of the window
  11664.      and the window was active, SystemClick sends the mouse-down event to
  11665.      the desk accessory, which processes it as appropriate.
  11666.   •  If the mouse button was pressed in the content region and the window
  11667.      was inactive, SystemClick makes it the active window.
  11668.   •  If the mouse button was pressed in the drag region, SystemClick calls
  11669.      the Window Manager procedure DragWindow to pull an outline of the window
  11670.      across the screen and move the window to a new location. If the window
  11671.      was inactive, DragWindow also makes it the active window (unless the
  11672.      Command key was pressed along with the mouse button).
  11673.   •  If the mouse button was pressed in the go-away region, SystemClick calls
  11674.      the Window Manager function TrackGoAway to determine whether the mouse
  11675.      is still inside the go-away region when the click is completed:  If
  11676.      so, it tells the desk accessory to close itself; otherwise, it does
  11677.      nothing.
  11678.  
  11679. æKY SystemEdit
  11680. æFc Desk.h
  11681. æT Function
  11682. æTN A9C2
  11683. æD pascal Boolean SystemEdit(short editCmd)
  11684.     = 0xA9C2; 
  11685. æDT Boolean myVariable = SystemEdit((short) editCmd);
  11686. æMM
  11687. æRT 180, 215
  11688. æRI I-441
  11689. æC 
  11690. Assembly-language note:  The macro you invoke to call SystemEdit from
  11691.                          assembly language is named _SysEdit.
  11692.  
  11693. Call SystemEdit when there’s a mouse-down event in the menu bar and the user chooses
  11694. one of the five standard editing commands from the Edit menu. Pass one of the following
  11695. as the value of the editCmd parameter:
  11696.  
  11697.   editCmd    Editing command
  11698.  
  11699.     0            Undo
  11700.     2            Cut
  11701.     3            Copy
  11702.     4            Paste
  11703.     5            Clear
  11704.  
  11705. If your Edit menu contains these five commands in the standard arrangement (the order
  11706. listed above, with a dividing line between Undo and Cut), you can simply call
  11707.  
  11708.   SystemEdit(menuItem-1)
  11709.  
  11710. where menuItem is the menu item number.
  11711.  
  11712. If the active window doesn’t belong to a desk accessory, SystemEdit returns FALSE;
  11713. the application should then process the editing command as usual. If the active
  11714. window does belong to a desk accessory, SystemEdit asks that accessory to process the
  11715. command and returns TRUE; in this case, the application should ignore the command.
  11716.  
  11717. Note:  It’s up to the application to make sure desk accessories get
  11718.        their editing commands that are chosen from the Edit menu. In
  11719.        particular, make sure your application hasn’t disabled the Edit
  11720.        menu or any of the five standard commands when a desk accessory
  11721.        is activated.
  11722.  
  11723. æKY SystemTask
  11724. æFc Desk.h
  11725. æT Function
  11726. æTN A9B4
  11727. æD pascal void SystemTask(void)
  11728.     = 0xA9B4; 
  11729. æDT SystemTask()(void);
  11730. æRT 85
  11731. æRI I-442, 444, II-189, N85-1
  11732. æC 
  11733. For each open desk accessory (or other device driver performing periodic actions),
  11734. SystemTask causes the accessory to perform the periodic action defined for it, if any
  11735. such action has been defined and if the proper time period has passed since the
  11736. action was last performed. For example, a clock accessory can be defined such that
  11737. the second hand is to move once every second; the periodic action for the accessory
  11738. will be to move the second hand to the next position, and SystemTask will alert the
  11739. accessory every second to perform that action.
  11740.  
  11741. You should call SystemTask as often as possible, usually once every time through your
  11742. main event loop. Call it more than once if your application does an unusually large
  11743. amount of processing each time through the loop.
  11744.  
  11745. Note:  SystemTask should be called at least every sixtieth of a second.
  11746.  
  11747. æKY SystemEvent
  11748. æFc Desk.h
  11749. æT Function
  11750. æTN A9B2
  11751. æD pascal Boolean SystemEvent(const EventRecord *theEvent)
  11752.     = 0xA9B2; 
  11753. æDT Boolean myVariable = SystemEvent((const EventRecord *) theEvent);
  11754. æRT 5,85
  11755. æRI I-442, N5-1, N85-1
  11756. æC  
  11757. SystemEvent is called only by the Toolbox Event Manager function GetNextEvent when it
  11758. receives an event, to determine whether the event should be handled by the application
  11759. or by the system. If the given event should be handled by the application, SystemEvent
  11760. returns FALSE; otherwise, it calls the appropriate system code to handle the event
  11761. and returns TRUE.
  11762.  
  11763. In the case of a null or mouse-down event, SystemEvent does nothing but return FALSE.
  11764. Notice that it responds this way to a mouse-down event even though the event may in
  11765. fact have occurred in a system window (and therefore may have to be handled by the
  11766. system). The reason for this is that the check for exactly where the event occurred
  11767. (via the Window Manager function FindWindow) is made later by the application and so
  11768. would be made twice if SystemEvent were also to do it. To avoid this duplication,
  11769. SystemEvent passes the event on to the application and lets it make the sole call to
  11770. FindWindow. Should FindWindow reveal that the mouse-down event did occur in a system
  11771. window, the application can then call SystemClick, as described above, to get the
  11772. system to handle it.
  11773.  
  11774. If the given event is a mouse-up or any keyboard event (including keyboard equivalents
  11775. of commands), SystemEvent checks whether the active window belongs to a desk accessory
  11776. and whether that accessory can handle this type of event. If so, it sends the event
  11777. to the desk accessory and returns TRUE; otherwise, it returns FALSE.
  11778.  
  11779. If SystemEvent is passed an activate or update event, it checks whether the window
  11780. the event occurred in is a system window belonging to a desk accessory and whether
  11781. that accessory can handle this type of event. If so, it sends the event to the desk
  11782. accessory and returns TRUE; otherwise, it returns FALSE.
  11783.  
  11784. Note:  It’s unlikely that a desk accessory would not be set up to handle
  11785.        keyboard, activate, and update events, or that it would handle
  11786.        mouse-up events.
  11787.  
  11788.        If the given event is a disk-inserted event, SystemEvent does some
  11789.        low-level processing (by calling the File Manager function MountVol)
  11790.        but passes the event on to the application by returning FALSE, in
  11791.        case the application wants to do further processing. Finally,
  11792.        SystemEvent returns FALSE for network, device driver, and
  11793.        application-defined events.
  11794.  
  11795. Assembly-language note:  Advanced programmers can make SystemEvent
  11796.                          always return FALSE by setting the global
  11797.                          variable SEvtEnb (a byte) to 0.
  11798.  
  11799. æKY SystemMenu
  11800. æFc Desk.h
  11801. æT Function
  11802. æTN A9B5
  11803. æD pascal void SystemMenu(long menuResult)
  11804.     = 0xA9B5; 
  11805. æDT SystemMenu((long) menuResult);
  11806. æMM
  11807. æRI I-443
  11808. æC  
  11809. SystemMenu is called only by the Menu Manager functions MenuSelect and MenuKey, when
  11810. an item in a menu belonging to a desk accessory has been chosen. The menuResult
  11811. parameter has the same format as the value returned by MenuSelect and MenuKey:  the
  11812. menu ID in the high-order word and the menu item number in the low-order word. (The
  11813. menu ID will be negative.) SystemMenu directs the desk accessory to perform the
  11814. appropriate action for the given menu item.
  11815.  
  11816. æKY opendeskacc
  11817. æFc Desk.h
  11818. æT Function
  11819. æD short opendeskacc(char *theAcc); 
  11820. æDT short myVariable = opendeskacc((char *) theAcc);
  11821. æMM
  11822. æRI I-440
  11823. æC 
  11824. OpenDeskAcc opens the desk accessory having the given name and displays its window
  11825. (if any) as the active window. The name is the accessory’s resource name, which you
  11826. get from the Apple menu by calling the Menu Manager procedure GetItem. OpenDeskAcc
  11827. calls the Resource Manager to read the desk accessory from the resource file into the
  11828. application heap.
  11829.  
  11830. You should ignore the value returned by OpenDeskAcc. If the desk accessory is successfully
  11831. opened, the function result is its driver reference number. However, if the desk
  11832. accessory can’t be opened, the function result is undefined; the accessory will have
  11833. taken care of informing the user of the problem (such as memory full) and won’t
  11834. display itself.
  11835.  
  11836. Warning:  Early versions of some desk accessories may set the current
  11837.           grafPort to the accessory’s port upon return from OpenDeskAcc.
  11838.           To be safe, you should bracket your call to OpenDeskAcc with
  11839.           calls to the QuickDraw procedures GetPort and SetPort, to save
  11840.           and restore the current port.
  11841.  
  11842. Note:  Programmers concerned about the amount of available memory should
  11843.        be aware that an open desk accessory uses from 1K to 3K bytes of
  11844.        heap space in addition to the space needed for the accessory itself.
  11845.        The desk accessory is responsible for determining whether there is
  11846.        sufficient memory for it to run; this can be done by calling
  11847.        SizeResource followed by ResrvMem.
  11848.  
  11849.  
  11850. æKY DeskBus.h
  11851. æKL ADBOp
  11852. ADBReInit
  11853. CountADBs
  11854. GetADBInfo
  11855. GetIndADB
  11856. SetADBInfo
  11857.  
  11858. ADBAddress
  11859. ADBDataBlock
  11860. ADBDBlkPtr
  11861. ADBOpBlock
  11862. ADBOpBPtr
  11863. ADBSetInfoBlock
  11864. ADBSInfoPtr
  11865.  
  11866. æKY ADBAddress
  11867. æFc DeskBus.h
  11868. æT typedef
  11869. æD typedef char ADBAddress;
  11870. æC 
  11871.  
  11872. æKY ADBOpBlock
  11873. ADBOpBPtr
  11874. æFc DeskBus.h
  11875. æT struct
  11876. æD struct ADBOpBlock {
  11877.     Ptr dataBuffPtr; /*address of data buffer*/
  11878.     Ptr opServiceRtPtr; /*service routine pointer*/
  11879.     Ptr opDataAreaPtr; /*optional data area address*/
  11880. };
  11881.  
  11882. typedef struct ADBOpBlock ADBOpBlock;
  11883. typedef ADBOpBlock *ADBOpBPtr;
  11884.  
  11885. æC 
  11886.  
  11887. æKY ADBDataBlock
  11888. ADBDBlkPtr
  11889. æFc DeskBus.h
  11890. æT struct
  11891. æD struct ADBDataBlock {
  11892.     char devType; /*device type*/
  11893.     char origADBAddr; /*original ADB Address*/
  11894.     Ptr dbServiceRtPtr; /*service routine pointer*/
  11895.     Ptr dbDataAreaAddr; /*data area address*/
  11896. };
  11897.  
  11898. typedef struct ADBDataBlock ADBDataBlock;
  11899. typedef ADBDataBlock *ADBDBlkPtr;
  11900.  
  11901. æC 
  11902.  
  11903. æKY ADBSetInfoBlock
  11904. ADBSInfoPtr
  11905. æFc DeskBus.h
  11906. æT struct
  11907. æD struct ADBSetInfoBlock {
  11908.     Ptr siServiceRtPtr; /*service routine pointer*/
  11909.     Ptr siDataAreaAddr; /*data area address*/
  11910. };
  11911.  
  11912. typedef struct ADBSetInfoBlock ADBSetInfoBlock;
  11913. typedef ADBSetInfoBlock *ADBSInfoPtr;
  11914.  
  11915. æC 
  11916.  
  11917. æKY ADBReInit
  11918. æFc DeskBus.h
  11919. æT Function
  11920. æTN A07B
  11921. æD pascal void ADBReInit(void)
  11922.     = 0xA07B; 
  11923. æDT ADBReInit()(void);
  11924. æMM
  11925. æRT 143, 206 
  11926. æRI V-367, N143
  11927. æC 
  11928. Trap macro    _ADBReInit
  11929.  
  11930. ADBReInit reinitializes the entire Apple Desktop Bus. It clears the ADB device table
  11931. to zeros and places a SendReset command on the bus to reset all devices to their
  11932. original addresses. ADBReInit has no parameters.
  11933.  
  11934. Because it does not deallocate ADB resources on the system heap, ADBReInit should not
  11935. be used for routine bus initialization. Apple strongly recommends against adding
  11936. devices while the system is running; therefore, you should never call ADBReInit.
  11937.  
  11938. ADBReInit also calls a routine pointed to by the low memory global JADBProc
  11939. at the beginning and end of its execution.  You can insert your own
  11940. preprocessing/postprocessing routine by changing the value of JADBProc; ADBReInit
  11941. conditions it by setting D0 to 0 for preprocessing and to 1 for postprocessing.  Your
  11942. procedure must restore the value of D0 and branch to the original value of JADBProc
  11943. on exit.  JADBProc should be used to de-allocate memory used by the driver (see
  11944. MacDTS Sample Code “TbltDrvr” for an example), and then it should chain to the procedure
  11945. originally found in JADBProc.
  11946.  
  11947. The complete ADBReInit sequence is therefore the following:
  11948.  
  11949.   •  JSR to JADBProc with D0 set to 0
  11950.   •  reinitialize the Apple Desktop Bus
  11951.   •  clear the ADB device table
  11952.   •  JSR to JADBProc with D0 set to 1
  11953.  
  11954. æKY ADBOp
  11955. æFc DeskBus.h
  11956. æT Function
  11957. æD pascal OSErr ADBOp(Ptr data,ProcPtr compRout,Ptr buffer,short commandNum); 
  11958. æDT OSErr myVariable = ADBOp((Ptr) data,(ProcPtr) compRout,(Ptr) buffer,(short) commandNum);
  11959. æRT 206
  11960. æRI V-368
  11961. æC 
  11962. Trap macro    _ADBOp
  11963.  
  11964. On entry:    A0:  pointer to parameter block
  11965.              D0:  commandNum (byte)
  11966.  
  11967. Parameter block
  11968.     -->    0    buffer      pointer
  11969.     -->    4    compRout    pointer
  11970.     -->    8    data        pointer
  11971.  
  11972. On exit:     D0:  result code (byte)
  11973.  
  11974. The completion routine pointed to by compRout will be passed the following parameters
  11975. on entry:
  11976.  
  11977.              D0:  commandNum (byte)
  11978.              A0:  pointer to buffer, data stored as a Pascal string (maximum
  11979.                   8 bytes data preceded by one length byte)
  11980.              A1:  pointer to completion routine (compRout)
  11981.              A2:  pointer to optional data area (data)
  11982.  
  11983. ADBOp transmits over the bus the command byte whose value is given by commandNum. The
  11984. structure of the command byte is given earlier in Figure 1. ADBOp executes only when
  11985. the ADB is otherwise idle; otherwise it is held in a command queue. It returns an
  11986. error if the command queue is full. The length of the data buffer pointed to by
  11987. buffer is contained in its first byte, like a Pascal string. The optional data area
  11988. pointed to by data is for local storage by the completion routine pointed to by
  11989. compRout. ADBop should be used sparingly; it is not intended for polling a device. 
  11990. The host automatically polls devices with data to deliver.
  11991.  
  11992. Result codes    noErr    No error
  11993.                 –1       Unsuccessful completion
  11994.  
  11995. æKY CountADBs
  11996. æFc DeskBus.h
  11997. æT Function
  11998. æD pascal short CountADBs(void); 
  11999. æDT short myVariable = CountADBs()(void);
  12000. æRT 206
  12001. æRI V-369
  12002. æC 
  12003. Trap macro    _CountADBs
  12004.  
  12005. On exit:    D0:  number of devices (byte)
  12006.  
  12007. CountADBs returns a value representing the number of devices connected to the ADB by
  12008. counting the number of entries in the device table. It has no arguments and returns
  12009. no error codes.
  12010.  
  12011. æKY GetIndADB
  12012. æFc DeskBus.h
  12013. æT Function
  12014. æD pascal ADBAddress GetIndADB(ADBDataBlock *info,short devTableIndex); 
  12015. æDT ADBAddress myVariable = GetIndADB((ADBDataBlock *) info,(short) devTableIndex);
  12016. æRT 206
  12017. æRI V-369
  12018. æC 
  12019. Trap macro    _GetIndADB
  12020.  
  12021. On entry:    A0:  pointer to parameter block
  12022.              D0:  entry index number; range = 1..CountADBs (byte)
  12023.  
  12024. Parameter block
  12025.     <--    0    device type                byte    (handler ID)
  12026.     <--    1    original ADB address       byte
  12027.     <--    2    service routine address    pointer (compRout)
  12028.     <--    6    data area address          pointer (data)
  12029.  
  12030. On exit:     D0:  positive value:  current ADB address (byte)
  12031.                   negative value:  error code (byte)
  12032.  
  12033. GetIndADB returns information from the ADB device table entry whose index number is
  12034. given by devTableIndex. ADBDataBlock has this form:
  12035.  
  12036. TYPE  ADBDataBlock =
  12037.              PACKED RECORD
  12038.                devType:         SignedByte; {device type (handler ID)}
  12039.                origADBAddr:     SignedByte; {original ADB address}
  12040.                dbServiceRtPtr:  Ptr;        {service routine address (compRout)}
  12041.                dbDataAreaAddr:  Ptr         {data area address (data)}
  12042.              END;
  12043.  
  12044. GetIndADB returns the current ADB address of the device. If it is unable to complete
  12045. execution successfully, GetIndADB returns a negative value.
  12046.  
  12047. æKY GetADBInfo
  12048. æFc DeskBus.h
  12049. æT Function
  12050. æD pascal OSErr GetADBInfo(ADBDataBlock *info,ADBAddress adbAddr); 
  12051. æDT OSErr myVariable = GetADBInfo((ADBDataBlock *) info,(ADBAddress) adbAddr);
  12052. æRI V-370
  12053. æC 
  12054. Trap macro    _GetADBInfo
  12055.  
  12056. On entry:    A0:  pointer to parameter block
  12057.              D0:  ADB address of the device (byte)
  12058.  
  12059. Parameter block
  12060.     <--    0    device handler ID          byte
  12061.     <--    1    original ADB address       byte
  12062.     <--    2    service routine address    pointer (compRout)
  12063.     <--    6    data area address          pointer (data)
  12064.  
  12065. On exit:     D0:  result code (byte)
  12066.  
  12067. GetADBInfo returns information from the ADB device table entry of the device whose
  12068. ADB address is given by ABDAddr. The structure of ADBDataBlock is given above under
  12069. “GetIndADB”.
  12070.  
  12071. Result codes    noErr    No error
  12072.  
  12073. æKY SetADBInfo
  12074. æFc DeskBus.h
  12075. æT Function
  12076. æD pascal OSErr SetADBInfo(ADBSetInfoBlock *info,ADBAddress adbAddr); 
  12077. æDT OSErr myVariable = SetADBInfo((ADBSetInfoBlock *) info,(ADBAddress) adbAddr);
  12078. æRT 206
  12079. æRI V-370
  12080. æC 
  12081. Trap macro    _SetADBInfo
  12082.  
  12083. On entry:    A0:  pointer to parameter block
  12084.              D0:  ADB address of the device (byte)
  12085.  
  12086. Parameter block
  12087.     -->    0    service routine address    pointer (compRout)
  12088.     -->    4    data area address          pointer (data)
  12089.  
  12090. On exit:     D0:  result code (byte)
  12091.  
  12092. SetADBInfo sets the service routine address and the data area address in the ADB
  12093. device table entry for the device whose ADB address is given by ABDAddr. ADBSetInfoBlock
  12094. has this form:
  12095.  
  12096. TYPE  ADBSetInfoBlock =
  12097.                RECORD
  12098.                  siServiceRtPtr:  Ptr;  {service routine address (compRout)}
  12099.                  siDataAreaAddr:  Ptr   {data area address (data)}
  12100.                END;
  12101.  
  12102. Result codes    noErr    No error
  12103.  
  12104. Warning:  You should send a Flush command to the device after calling it
  12105.           with SetADBInfo, to prevent it sending old data to the new data
  12106.           area address.
  12107.  
  12108.  
  12109. æKY Devices.h
  12110. æKL CloseDriver
  12111. Control
  12112. GetDCtlEntry
  12113. KillIO
  12114. opendriver
  12115. OpenDriver
  12116. PBControl
  12117. PBKillIO
  12118. PBStatus
  12119. SetChooserAlert
  12120. Status
  12121.  
  12122. activDev
  12123. AuxDCE
  12124. AuxDCEHandle
  12125. AuxDCEPtr
  12126. buttonMsg
  12127. cdevGenErr
  12128. cdevMemErr
  12129. cdevResErr
  12130. cdevUnset
  12131. chooserID
  12132. clearDev
  12133. closeDev
  12134. copyDev
  12135. cursorDev
  12136. cutDev
  12137. DCtlEntry
  12138. DCtlHandle
  12139. DCtlPtr
  12140. deactivDev
  12141. deselectMsg
  12142. fillListMsg
  12143. getSelMsg
  12144. hitDev
  12145. initDev
  12146. keyEvtDev
  12147. macDev
  12148. newSelMsg
  12149. nulDev
  12150. pasteDev
  12151. selectMsg
  12152. terminateMsg
  12153. undoDev
  12154. updateDev
  12155.  
  12156. æKY newSelMsg
  12157. æFc Devices.h
  12158. æT #define
  12159. æD #define newSelMsg 12
  12160. æC 
  12161.  
  12162. æKY fillListMsg
  12163. æFc Devices.h
  12164. æT #define
  12165. æD #define fillListMsg 13
  12166. æC 
  12167.  
  12168. æKY getSelMsg
  12169. æFc Devices.h
  12170. æT #define
  12171. æD #define getSelMsg 14
  12172. æC 
  12173.  
  12174. æKY selectMsg
  12175. æFc Devices.h
  12176. æT #define
  12177. æD #define selectMsg 15
  12178. æC 
  12179.  
  12180. æKY deselectMsg
  12181. æFc Devices.h
  12182. æT #define
  12183. æD #define deselectMsg 16
  12184. æC 
  12185.  
  12186. æKY terminateMsg
  12187. æFc Devices.h
  12188. æT #define
  12189. æD #define terminateMsg 17
  12190. æC 
  12191.  
  12192. æKY buttonMsg
  12193. æFc Devices.h
  12194. æT #define
  12195. æD #define buttonMsg 19
  12196. æC 
  12197.  
  12198. æKY chooserID
  12199. æFc Devices.h
  12200. æT #define
  12201. æD #define chooserID 1
  12202. æC 
  12203.  
  12204. æKY initDev
  12205. æFc Devices.h
  12206. æT #define
  12207. æD #define initDev 0 /*Time for cdev to initialize itself*/
  12208. æC 
  12209. »The initDev Message
  12210.  
  12211. InitDev is an initialization message sent to allow the cdev to allocate its private
  12212. storage (if any) and do any initial settings to buttons or controls.  This message is
  12213. sent when the user clicks on the cdev’s icon.
  12214.  
  12215. Note that the dialog, cdev list, and all of the items in the cdev’s 'DITL' except
  12216. user items will already have been drawn when the initDev message is sent.
  12217.  
  12218. If your cdev doesn’t need any storage it should return the value that was passed to
  12219. it in cdevValue.
  12220.  
  12221. æKY hitDev
  12222. æFc Devices.h
  12223. æT #define
  12224. æD #define hitDev 1 /*Hit on one of my items*/
  12225. æC »The hitDev Message
  12226.  
  12227. A hitDev message is sent when the user has clicked an enabled dialog item that belongs
  12228. to the cdev.  The dialog item number of the item hit is passed in the Item parameter.
  12229.  Remember that the Control Panel’s items precede yours, so
  12230. you’ll want (Item – numItems) to determine which of your items was hit.  If the
  12231. Control Panel itself has n items, the first of the cdev’s items will be n+1 in the
  12232. combined dialog item list.  A cdev should not depend on any hardcoded value for
  12233. numItems, since the number of items in Control Panel’s 'DITL' is likely to change in
  12234. the future.
  12235.  
  12236. Factoring in numItems need not mean an increase in your code size, or passing and
  12237. adding numItems everywhere, or foregoing the constants that most developers use to
  12238. identify specific items.  You can do it easily, and neatly, as follows:
  12239.  
  12240.   1.  Subtract numItems from Item right away, and refer to your dialog
  12241.       items with constants as usual throughout the cdev.
  12242.   2.  Write simple envelope routines to enclose Dialog Manager procedures
  12243.       that require item number arguments.  Add numItems only locally,
  12244.       within those routines and for the Dialog Manager calls only.
  12245.  
  12246. This is demonstrated in the sample cdev.
  12247.  
  12248. æKY closeDev
  12249. æFc Devices.h
  12250. æT #define
  12251. æD #define closeDev 2 /*Close yourself*/
  12252. æC 
  12253.  
  12254. æKY nulDev
  12255. æFc Devices.h
  12256. æT #define
  12257. æD #define nulDev 3 /*Null event*/
  12258. æC »The nulDev Message
  12259.  
  12260. A nulDev message is sent to the cdev on every Control Panel run event.  This allows
  12261. the cdev to perform tasks that need to be executed continuously
  12262. (insertion point blinking, for example).
  12263.  
  12264. A cdev cannot assume any particular timing of calls from applications.  Don’t use
  12265. nulDev to refresh settings; see activDev, above.
  12266.  
  12267. æKY updateDev
  12268. æFc Devices.h
  12269. æT #define
  12270. æD #define updateDev 4 /*Update event*/
  12271. æC 
  12272.  
  12273. æKY activDev
  12274. æFc Devices.h
  12275. æT #define
  12276. æD #define activDev 5 /*Activate event*/
  12277. æC 
  12278. #define activDev 5 /*Activate event*/
  12279.  
  12280. »The activDev Message
  12281.  
  12282. An activDev message is sent to the cdev on every activate event.  It allows the cdev
  12283. to reset any items that may have changed while the Control Panel was inactive.   It
  12284. also allows the cdev to send things such as “lists activate” messages.
  12285.  
  12286. æKY deactivDev
  12287. æFc Devices.h
  12288. æT #define
  12289. æD #define deactivDev 6 /*Deactivate event*/
  12290. æC 
  12291.  
  12292. æKY keyEvtDev
  12293. æFc Devices.h
  12294. æT #define
  12295. æD #define keyEvtDev 7 /*Key down/auto key*/
  12296. æC »The keyEvtDev Message
  12297.  
  12298. A keyEvtDev message is sent to the cdev on every keyDown event and autoKey event.  It
  12299. allows the cdev to process key events.  On return to the Control Panel, the key event
  12300. will be processed by a call to dialogSelect in the Dialog Manager.  A cdev that does
  12301. not want the Toolbox Event Manager to do any further processing should change the
  12302. what field of the EventRecord to nullEvent before returning to the Control Panel.
  12303.  
  12304. æKY macDev
  12305. æFc Devices.h
  12306. æT #define
  12307. æD #define macDev 8 /*Decide whether or not to show up*/
  12308. æC 
  12309.  
  12310. »The macDev Message
  12311.  
  12312. If the 'mach' resource has a 0 in Softmask and a –1 ($FFFF) in Hardmask, the first
  12313. message a cdev will get is a macDev message.  This is an opportunity for the cdev to
  12314. determine whether it can run, and whether it should appear in the Control Panel’s
  12315. cdev list.  The cdev can do its own check to see which machine it is being run on,
  12316. what hardware is connected, and what is in the slots (if it has slots).  The cdev
  12317. must then return a function result of 1 or 0.  If  a 0 is returned, the Control Panel
  12318. will not display the cdev in the icon list.  (Note that the Control Panel does not
  12319. interpret this 0 or 1 as an error message as described under “Cdev Error Checking”.)
  12320.  
  12321. The macDev call happens only once, and only when Softmask and Hardmask are 0 and
  12322. FFFF.  It is always the first call made to the cdev.
  12323. #define macDev   8 /*Decide whether or not to show up*/
  12324.  
  12325. æKY undoDev
  12326. æFc Devices.h
  12327. æT #define
  12328. æD #define undoDev 9
  12329. æC 
  12330.  
  12331. æKY cutDev
  12332. æFc Devices.h
  12333. æT #define
  12334. æD #define cutDev 10
  12335. æC 
  12336.  
  12337. æKY copyDev
  12338. æFc Devices.h
  12339. æT #define
  12340. æD #define copyDev 11
  12341. æC 
  12342.  
  12343. æKY pasteDev
  12344. æFc Devices.h
  12345. æT #define
  12346. æD #define pasteDev 12
  12347. æC 
  12348.  
  12349. æKY clearDev
  12350. æFc Devices.h
  12351. æT #define
  12352. æD #define clearDev 13
  12353. æC 
  12354.  
  12355. æKY cursorDev
  12356. æFc Devices.h
  12357. æT #define
  12358. æD #define cursorDev 14
  12359. æC 
  12360.  
  12361. æKY cdevGenErr
  12362. æFc Devices.h
  12363. æT #define
  12364. æD #define cdevGenErr -1 /*General error; gray cdev w/o alert*/
  12365. æC 
  12366.  
  12367. æKY cdevMemErr
  12368. æFc Devices.h
  12369. æT #define
  12370. æD #define cdevMemErr 0 /*Memory shortfall; alert user please*/
  12371. æC 
  12372.  
  12373. æKY cdevResErr
  12374. æFc Devices.h
  12375. æT #define
  12376. æD #define cdevResErr 1 /*Couldn't get a needed resource; alert*/
  12377. æC 
  12378.  
  12379. æKY cdevUnset
  12380. æFc Devices.h
  12381. æT #define
  12382. æD #define cdevUnset 3 /* cdevValue is initialized to this*/
  12383. æC 
  12384. »CDEV ERROR CHECKING
  12385. _______________________________________________________________________________
  12386.  
  12387. Because a desk accessory may be called into many strange and wonderful situations,
  12388. careful attention must be paid to error checking.  The two most common error conditions
  12389. are missing resources and lack of memory.  Some error reporting and recovery facilities
  12390. have been provided in the Control Panel to help with errors encountered in a cdev.
  12391.  
  12392. Because the Control Panel has no direct information about the cdev, the cdev’s code
  12393. must be able to detect and recover from error conditions on its own.  If the recovery
  12394. cannot be effected the cdev must dispose of any memory it has allocated, and exit
  12395. back to the Control Panel with an error code.
  12396.  
  12397. Following a shutdown, the Control Panel can help report the error condition to the
  12398. user and prevent accidental reentry into the cdev that might result from such things
  12399. as an update event.  A cdev can request three different error reporting mechanisms
  12400. from the Control Panel:
  12401.  
  12402.   •  If a memory error has occured, then, after the cdev has safely shut
  12403.      itself down, it may request the Control Panel to issue an out-of-memory
  12404.      error message and gray out (paint over with the background pattern) the
  12405.      cdev area of the Control Panel window.  It will remain grayed until
  12406.      another cdev is selected.  The Control Panel window itself is not
  12407.      closed since other cdevs may still be able to function in the environment.
  12408.   •  If a resource error is detected, the cdev may request that a
  12409.      can’t-find-needed-resource error message be issued.
  12410.   •  The cdev may display its own error message and then call on the
  12411.      Control Panel to gray its area.
  12412.  
  12413. The Control Panel uses the cdevValue parameter to send status information to the
  12414. cdev, and a proper cdev uses its function value to send information back to the
  12415. Control Panel.  In the absence of errors, the same value passes back and forth: the
  12416. Control Panel puts the last function value it received into cdevValue when it calls
  12417. the cdev; the cdev returns the value it finds there as the function value.  The cdev
  12418. may want to keep a handle to its own storage, in which case passing it as the function
  12419. value ensures its availability, since the Control Panel will pass it back in cdevValue
  12420. at the next call.
  12421.  
  12422. Four constants have been defined for this cdev/Control Panel communication:
  12423.  
  12424. #define  cdevUnset        3    /*initial value passed in cdevValue*/
  12425. #define  cdevGenErr      -1    /*generic cdev error*/
  12426. #define  cdevMemErr       0    /*insufficient memory for cdev execution*/
  12427. #define  cdevResErr       1    /*missing resource needed by cdev*/
  12428.  
  12429. After the macDev call, the Control Panel sends cdevUnset in cdevValue, so that until
  12430. an error occurs or the cdev uses its function value as a handle, cdevUnset is passed
  12431. back and forth.  If the cdev encounters an error, it should dispose of all handles
  12432. and pointers it has set up, strip the stack back to the same position as a normal
  12433. exit, and return one of the three error codes as the function result.  The Control
  12434. Panel will respond as follows:
  12435.  
  12436.   Function           Message to                     Control Panel Action    
  12437.   Result             Control Panel   
  12438.  
  12439.   cdevGenErr         The cdev has encountered an    Gray out the cdev’s area,
  12440.                      error from which it cannot     send a 0 in cdevValue in
  12441.                      recover, but do not put up     succeeding cdev calls
  12442.                      an error dialog.
  12443.  
  12444.   cdevMemErr         The cdev has determined that   Gray out cdev’s area, put
  12445.                      there is not enough memory to  up error dialog, send a 0
  12446.                      execute; please put up a       in cdevValue in succeeding
  12447.                      memory error dialog.           cdev calls.
  12448.  
  12449.   cdevResErr         The cdev can’t find a needed   Gray out cdev’s area, put
  12450.                      resource; please put up a      up error dialog, send a 0
  12451.                      resource error dialog.         in cdevValue in succeeding
  12452.                                                     cdev calls.
  12453.  
  12454.   all other values,  No error conditions.           Send the value back in
  12455.   either handles                                    cdevValue.
  12456.   or cdevUnset
  12457.  
  12458. The cdev code should check cdevValue at entry.  A 0 means that the Control Panel has
  12459. responded to a cdev error message by shutting down the cdev and displaying an error
  12460. dialog if one was requested.  The cdev should immediately exit.
  12461.  
  12462. Once the Control Panel has responded to an error message from a cdev it will no
  12463. longer respond to any return values until another cdev is launched.
  12464.  
  12465. æKY DCtlEntry
  12466. DCtlPtr
  12467. DCtlHandle
  12468. æFc Devices.h
  12469. æT struct
  12470. æD struct DCtlEntry {
  12471.     Ptr dCtlDriver;
  12472.     short dCtlFlags;
  12473.     QHdr dCtlQHdr;
  12474.     long dCtlPosition;
  12475.     Handle dCtlStorage;
  12476.     short dCtlRefNum;
  12477.     long dCtlCurTicks;
  12478.     WindowPtr dCtlWindow;
  12479.     short dCtlDelay;
  12480.     short dCtlEMask;
  12481.     short dCtlMenu;
  12482. };
  12483.  
  12484. typedef struct DCtlEntry DCtlEntry;
  12485. typedef DCtlEntry *DCtlPtr, **DCtlHandle;
  12486.  
  12487. æC 
  12488. »Device Control Entry
  12489.  
  12490. The first time a driver is opened, information about it is read into a structure in
  12491. memory called a device control entry. A device control entry contains the header of
  12492. the driver’s I/O queue, the location of the driver’s routines, and other information.
  12493. A device control entry is a 40-byte relocatable block located in the system heap.
  12494. It’s locked while the driver is open, and unlocked while the driver is closed.
  12495.  
  12496. Most of the data in the device control entry is stored and accessed only by the
  12497. Device Manager, but in some cases the driver itself must store into it. The structure
  12498. of a device control entry is shown below; note that the first four words of the
  12499. driver are copied into the dCtlFlags, dCtlDelay, dCtlEMask, and dCtlMenu fields.
  12500.  
  12501. TYPE  DCtlEntry = RECORD
  12502.                     dCtlDriver:    Ptr;        {pointer to ROM driver or }
  12503.                                                { handle to RAM driver}
  12504.                     dCtlFlags:     INTEGER;    {flags}
  12505.                     dCtlQHdr:      QHdr;       {driver I/O queue header}
  12506.                     dCtlPosition:  LONGINT;    {byte position used by Read }
  12507.                                                { and Write calls}
  12508.                     dCtlStorage:   Handle;     {handle to RAM driver's }
  12509.                                                { private storage}
  12510.                     dCtlRefNum:    INTEGER;    {driver reference number}
  12511.                     dCtlCurTicks:  LONGINT;    {used internally}
  12512.                     dCtlWindow:    WindowPtr;  {pointer to driver's window}
  12513.                     dCtlDelay:     INTEGER;    {number of ticks between }
  12514.                                                { periodic actions}
  12515.                     dCtlEMask:     INTEGER;    {desk accessory event mask}
  12516.                     dCtlMenu:      INTEGER     {menu ID of menu associated
  12517.                                                { with driver}
  12518.                   END;
  12519.  
  12520.       DCtlPtr    = ^DCtlEntry;
  12521.       DCtlHandle = ^DCtlPtr;
  12522.  
  12523. The low-order byte of the dCtlFlags word contains the following flags:
  12524.  
  12525. Bit number    Meaning
  12526.  
  12527.     5         Set if driver is open
  12528.     6         Set if driver is RAM-based
  12529.     7         Set if driver is currently executing
  12530.  
  12531. Assembly-language note:  These flags can be accessed with the global
  12532.                          constants dOpened, dRAMBased, and drvrActive.
  12533.  
  12534. The high-order byte of the dCtlFlags word contains flags copied from the drvrFlags
  12535. word of the driver, as described above.
  12536.  
  12537. DCtlQHdr contains the header of the driver’s I/O queue (described below). DCtlPosition
  12538. is used only by drivers of block devices, and indicates the current source or destination
  12539. position of a Read or Write call. The position is given as a number of bytes beyond
  12540. the physical beginning of the medium used by the device. For example, if one logical
  12541. block of data has just been read from a 3 1/2-inch disk via the Disk Driver, dCtlPosition
  12542. will be 512.
  12543.  
  12544. ROM drivers generally use locations in low memory for their local storage. RAM drivers
  12545. may reserve memory within their code space, or allocate a relocatable block and keep
  12546. a handle to it in dCtlStorage (if the block resides in the application heap, its
  12547. handle will be set to NIL when the heap is reinitialized).
  12548.  
  12549. You can get a handle to a driver’s device control entry by calling the Device Manager
  12550. function GetDCtlEntry.
  12551.  
  12552. æKY AuxDCE
  12553. AuxDCEPtr
  12554. AuxDCEHandle
  12555. æFc Devices.h
  12556. æT struct
  12557. æD struct AuxDCE {
  12558.     Ptr dCtlDriver;
  12559.     short dCtlFlags;
  12560.     QHdr dCtlQHdr;
  12561.     long dCtlPosition;
  12562.     Handle dCtlStorage;
  12563.     short dCtlRefNum;
  12564.     long dCtlCurTicks;
  12565.     GrafPtr dCtlWindow;
  12566.     short dCtlDelay;
  12567.     short dCtlEMask;
  12568.     short dCtlMenu;
  12569.     char dCtlSlot;
  12570.     char dCtlSlotId;
  12571.     long dCtlDevBase;
  12572.     Ptr dCtlOwner;
  12573.     char dCtlExtDev;
  12574.     char fillByte;
  12575. };
  12576.  
  12577. typedef struct AuxDCE AuxDCE;
  12578. typedef AuxDCE *AuxDCEPtr, **AuxDCEHandle;
  12579.  
  12580. æC 
  12581.  
  12582. æKY GetDCtlEntry
  12583. æFc Devices.h
  12584. æT Function
  12585. æD pascal DCtlHandle GetDCtlEntry(short refNum); 
  12586. æDT DCtlHandle myVariable = GetDCtlEntry((short) refNum);
  12587. æMM
  12588. æRT 71
  12589. æRI II-190
  12590. æC 
  12591.  
  12592. æKY SetChooserAlert
  12593. æFc Devices.h
  12594. æT Function
  12595. æD pascal Boolean SetChooserAlert(Boolean f); 
  12596. æDT Boolean myVariable = SetChooserAlert((Boolean) f);
  12597. æRI V-431
  12598. æC 
  12599. If f is true, the Chooser will put up the page setup alert; if f is false
  12600. it won’t.  SetChooserAlert returns the original alert state.  The 
  12601. application should restore the original alert state when it exits.
  12602. _____________________________________________________________________________________
  12603. Assembly-language note:  If the psAlert bit of the low-memory global
  12604. HiliteMode is 0 then no page setup alert will be generated. 
  12605. Applications that set or clear this bit must be sure not to affect
  12606. any other bits in the byte and to restore the bit as they leave.
  12607.      
  12608. HiliteMode  equ  $938
  12609. psAlert     equ  6
  12610. bclr        #psAlert,HiliteMode
  12611. bset        #psAlert,HiliteMode
  12612. _____________________________________________________________________________________
  12613.  
  12614. æKY OpenDriver
  12615. æFc Devices.h
  12616. æT Function
  12617. æD pascal OSErr OpenDriver(const Str255 name,short *drvrRefNum); 
  12618. æDT OSErr myVariable = OpenDriver((const Str255) name,(short *) drvrRefNum);
  12619. æMM
  12620. æRI II-178, N14-2
  12621. æC 
  12622. [Not in ROM]
  12623.  
  12624. OpenDriver opens the device driver specified by name and returns its reference number
  12625. in refNum.
  12626.  
  12627. Result codes    noErr           No error
  12628.                 badUnitErr      Bad reference number
  12629.                 dInstErr        Couldn’t find driver in resource file
  12630.                 openErr         Driver can’t perform the requested
  12631.                                 reading or writing
  12632.                 unitEmptyErr    Bad reference number
  12633.  
  12634. æKY opendriver
  12635. æFc Devices.h
  12636. æT Function
  12637. æD OSErr opendriver(char *driverName,short *refNum); 
  12638. æDT OSErr myVariable = opendriver((char *) driverName,(short *) refNum);
  12639. æC 
  12640.  
  12641. æKY CloseDriver
  12642. æFc Devices.h
  12643. æT Function
  12644. æD pascal OSErr CloseDriver(short refNum); 
  12645. æDT OSErr myVariable = CloseDriver((short) refNum);
  12646. æRI II-178
  12647. æC 
  12648. [Not in ROM]
  12649.  
  12650. CloseDriver closes the device driver having the reference number refNum. Any pending
  12651. I/O is completed, and the memory used by the driver is released.
  12652.  
  12653. Warning:  Before using this command to close a particular driver, refer
  12654.           to the chapter describing the driver for the consequences of
  12655.           closing it.
  12656.  
  12657. Result codes    noErr           No error
  12658.                 badUnitErr      Bad reference number
  12659.                 dRemoveErr      Attempt to remove an open driver
  12660.                 unitEmptyErr    Bad reference number
  12661.  
  12662. æKY Control
  12663. æFc Devices.h
  12664. æT Function
  12665. æD pascal OSErr Control(short refNum,short csCode,Ptr csParamPtr); 
  12666. æDT OSErr myVariable = Control((short) refNum,(short) csCode,(Ptr) csParamPtr);
  12667. æMM
  12668. æRI II-186
  12669. æC 
  12670. [Not in ROM]
  12671.  
  12672. Control sends control information to the device driver having the reference number
  12673. refNum. The type of information sent is specified by csCode, and the information
  12674. itself is pointed to by csParamPtr. The values passed in csCode and pointed to by
  12675. csParamPtr depend on the driver being called.
  12676.  
  12677. Result codes    noErr           No error
  12678.                 badUnitErr      Bad reference number
  12679.                 notOpenErr      Driver isn’t open
  12680.                 unitEmptyErr    Bad reference number
  12681.                 controlErr      Driver can’t respond to this Control call
  12682.  
  12683. æKY Status
  12684. æFc Devices.h
  12685. æT Function
  12686. æD pascal OSErr Status(short refNum,short csCode,Ptr csParamPtr); 
  12687. æDT OSErr myVariable = Status((short) refNum,(short) csCode,(Ptr) csParamPtr);
  12688. æMM
  12689. æRI II-186
  12690. æC 
  12691. [Not in ROM]
  12692.  
  12693. Status returns status information about the device driver having the reference number
  12694. refNum. The type of information returned is specified by csCode, and the information
  12695. itself is pointed to by csParamPtr. The values passed in csCode and pointed to by
  12696. csParamPtr depend on the driver being called.
  12697.  
  12698. Result codes    noErr           No error
  12699.                 badUnitErr      Bad reference number
  12700.                 notOpenErr      Driver isn’t open
  12701.                 unitEmptyErr    Bad reference number
  12702.                 statusErr       Driver can’t respond to this Status call
  12703.  
  12704. æKY KillIO
  12705. æFc Devices.h
  12706. æT Function
  12707. æD pascal OSErr KillIO(short refNum); 
  12708. æDT OSErr myVariable = KillIO((short) refNum);
  12709. æRI II-179 
  12710. æC 
  12711. [Not in ROM]
  12712.  
  12713. KillIO terminates all current and pending I/O with the device driver having the
  12714. reference number refNum.
  12715.  
  12716. Result codes    noErr           No error
  12717.                 badUnitErr      Bad reference number
  12718.  
  12719. æKY PBControl
  12720. æFc Devices.h
  12721. æT Function
  12722. æD pascal OSErr PBControl(ParmBlkPtr paramBlock,Boolean aSync); 
  12723. æDT OSErr myVariable = PBControl((ParmBlkPtr) paramBlock,(Boolean) aSync);
  12724. æMM
  12725. æRI II-186
  12726. æC 
  12727. Trap macro    _Control
  12728.  
  12729. Parameter block
  12730.   -->    12    ioCompletion  pointer
  12731.   <--    16    ioResult      word
  12732.   -->    22    ioVRefNum     word
  12733.   -->    24    ioRefNum      word
  12734.   -->    26    csCode        word
  12735.   -->    28    csParam       record
  12736.  
  12737. PBControl sends control information to the device driver having the reference number
  12738. ioRefNum; the drive number, if any, is specified by ioVRefNum. The type of information
  12739. sent is specified by csCode, and the information itself begins at csParam. The values
  12740. passed in csCode and csParam depend on the driver being called.
  12741.  
  12742. Result codes    noErr           No error
  12743.                 badUnitErr      Bad reference number
  12744.                 notOpenErr      Driver isn’t open
  12745.                 unitEmptyErr    Bad reference number
  12746.                 controlErr      Driver can’t respond to this Control call
  12747.  
  12748. æKY PBStatus
  12749. æFc Devices.h
  12750. æT Function
  12751. æD pascal OSErr PBStatus(ParmBlkPtr paramBlock,Boolean aSync); 
  12752. æDT OSErr myVariable = PBStatus((ParmBlkPtr) paramBlock,(Boolean) aSync);
  12753. æMM
  12754. æRI II-186
  12755. æC 
  12756. Trap macro    _Status
  12757.  
  12758. Parameter block
  12759.   -->    12    ioCompletion  pointer
  12760.   <--    16    ioResult      word
  12761.   -->    22    ioVRefNum     word
  12762.   -->    24    ioRefNum      word
  12763.   -->    26    csCode        word
  12764.   <--    28    csParam       record
  12765.  
  12766. PBStatus returns status information about the device driver having the reference
  12767. number ioRefNum; the drive number, if any, is specified by ioVRefNum. The type of
  12768. information returned is specified by csCode, and the information itself begins at
  12769. csParam. The values passed in csCode and csParam depend on the driver being called.
  12770.  
  12771. Result codes    noErr           No error
  12772.                 badUnitErr      Bad reference number
  12773.                 notOpenErr      Driver isn’t open
  12774.                 unitEmptyErr    Bad reference number
  12775.                 statusErr       Driver can’t respond to this Status call
  12776.  
  12777. æKY PBKillIO
  12778. æFc Devices.h
  12779. æT Function
  12780. æD pascal OSErr PBKillIO(ParmBlkPtr paramBlock,Boolean aSync); 
  12781. æDT OSErr myVariable = PBKillIO((ParmBlkPtr) paramBlock,(Boolean) aSync);
  12782. æRI II-187
  12783. æC 
  12784. Trap macro    _KillIO
  12785.  
  12786. Parameter block
  12787.   -->    12    ioCompletion  pointer
  12788.   <--    16    ioResult      word
  12789.   -->    24    ioRefNum      word
  12790.  
  12791. PBKillIO stops any current I/O request being processed, and removes all pending I/O
  12792. requests from the I/O queue of the device driver having the reference number ioRefNum.
  12793. The completion routine of each pending I/O request is called, with the ioResult field
  12794. of each request equal to the result code abortErr.
  12795.  
  12796. Result codes    noErr           No error
  12797.                 badUnitErr      Bad reference number
  12798.                 unitEmptyErr    Bad reference number
  12799.  
  12800.  
  12801. æKY Dialogs.h
  12802. æKL Alert
  12803. CautionAlert
  12804. CloseDialog
  12805. CouldAlert
  12806. CouldDialog
  12807. DialogSelect
  12808. DisposDialog
  12809. DlgCopy
  12810. DlgCut
  12811. DlgDelete
  12812. DlgPaste
  12813. DrawDialog
  12814. ErrorSound
  12815. findditem
  12816. FindDItem
  12817. FreeAlert
  12818. FreeDialog
  12819. GetAlrtStage
  12820. GetDItem
  12821. getitext
  12822. GetIText
  12823. GetNewDialog
  12824. HideDItem
  12825. InitDialogs
  12826. IsDialogEvent
  12827. ModalDialog
  12828. newcdialog
  12829. NewCDialog
  12830. newdialog
  12831. NewDialog
  12832. NoteAlert
  12833. paramtext
  12834. ParamText
  12835. ResetAlrtStage
  12836. SelIText
  12837. SetDAFont
  12838. SetDItem
  12839. setitext
  12840. SetIText
  12841. ShowDItem
  12842. StopAlert
  12843. UpdtDialog
  12844.  
  12845. AlertTemplate
  12846. AlertTHndl
  12847. AlertTPtr
  12848. btnCtrl
  12849. cancel
  12850. cautionIcon
  12851. chkCtrl
  12852. ctrlItem
  12853. DialogPeek
  12854. DialogPtr
  12855. DialogRecord
  12856. DialogTemplate
  12857. DialogTHndl
  12858. DialogTPtr
  12859. editText
  12860. iconItem
  12861. itemDisable
  12862. noteIcon
  12863. ok
  12864. picItem
  12865. radCtrl
  12866. resCtrl
  12867. ResumeProcPtr
  12868. SoundProcPtr
  12869. StageList
  12870. statText
  12871. stopIcon
  12872. userItem
  12873.  
  12874. æKY ctrlItem
  12875. æFc Dialogs.h
  12876. æT #define
  12877. æD #define ctrlItem 4
  12878. æC 
  12879.  
  12880. æKY btnCtrl
  12881. æFc Dialogs.h
  12882. æT #define
  12883. æD #define btnCtrl 0
  12884. æC 
  12885.  
  12886. æKY chkCtrl
  12887. æFc Dialogs.h
  12888. æT #define
  12889. æD #define chkCtrl 1
  12890. æC 
  12891.  
  12892. æKY radCtrl
  12893. æFc Dialogs.h
  12894. æT #define
  12895. æD #define radCtrl 2
  12896. æC 
  12897.  
  12898. æKY resCtrl
  12899. æFc Dialogs.h
  12900. æT #define
  12901. æD #define resCtrl 3
  12902. æC 
  12903.  
  12904. æKY statText
  12905. æFc Dialogs.h
  12906. æT #define
  12907. æD #define statText 8
  12908. æC 
  12909.  
  12910. æKY editText
  12911. æFc Dialogs.h
  12912. æT #define
  12913. æD #define editText 16
  12914. æC 
  12915.  
  12916. æKY iconItem
  12917. æFc Dialogs.h
  12918. æT #define
  12919. æD #define iconItem 32
  12920. æC 
  12921.  
  12922. æKY picItem
  12923. æFc Dialogs.h
  12924. æT #define
  12925. æD #define picItem 64
  12926. æC 
  12927.  
  12928. æKY userItem
  12929. æFc Dialogs.h
  12930. æT #define
  12931. æD #define userItem 0
  12932. æC 
  12933.  
  12934. æKY itemDisable
  12935. æFc Dialogs.h
  12936. æT #define
  12937. æD #define itemDisable 128
  12938. æC 
  12939.  
  12940. æKY ok
  12941. æFc Dialogs.h
  12942. æT #define
  12943. æD #define ok 1
  12944. æC 
  12945.  
  12946. æKY cancel
  12947. æFc Dialogs.h
  12948. æT #define
  12949. æD #define cancel 2
  12950. æC 
  12951.  
  12952. æKY stopIcon
  12953. æFc Dialogs.h
  12954. æT #define
  12955. æD #define stopIcon 0
  12956. æC 
  12957.  
  12958. æKY noteIcon
  12959. æFc Dialogs.h
  12960. æT #define
  12961. æD #define noteIcon 1
  12962. æC 
  12963.  
  12964. æKY cautionIcon
  12965. æFc Dialogs.h
  12966. æT #define
  12967. æD #define cautionIcon 2
  12968. æC 
  12969.  
  12970. æKY StageList
  12971. æFc Dialogs.h
  12972. æT typedef
  12973. æD typedef short StageList;
  12974. æC »Alert Templates in Memory
  12975.  
  12976. The data structure of an alert template is as follows:
  12977.  
  12978. TYPE AlertTemplate = RECORD
  12979.                        boundsRect:  Rect;      {becomes window's portRect}
  12980.                        itemsID:     INTEGER;   {resource ID of item list}
  12981.                        stages:      StageList  {alert stage information}
  12982.                      END;
  12983.  
  12984. BoundsRect is the rectangle that becomes the portRect of the window's grafPort. The
  12985. itemsID field contains the resource ID of the item list for the alert.
  12986.  
  12987. The information in the stages field determines exactly what should happen at each
  12988. stage of the alert. It's packed into a word that has the following structure:
  12989.  
  12990. TYPE StageList = PACKED RECORD
  12991.                    boldItm4:  0..1;     {default button item number minus 1}
  12992.                    boxDrwn4:  BOOLEAN;  {TRUE if alert box to be drawn}
  12993.                    sound4:    0..3      {sound number}
  12994.                    boldItm3:  0..1; 
  12995.                    boxDrwn3:  BOOLEAN; 
  12996.                    sound3:    0..3 
  12997.                    boldItm2:  0..1; 
  12998.                    boxDrwn2:  BOOLEAN; 
  12999.                    sound2:    0..3 
  13000.                    boldItm1:  0..1; 
  13001.                    boxDrwn1:  BOOLEAN; 
  13002.                    sound1:    0..3 
  13003.                  END;
  13004.  
  13005. Notice that the information is stored in reverse order—for the fourth stage first,
  13006. and for the first stage last.
  13007.  
  13008. The boldItm field indicates which button should be the default button (and therefore
  13009. boldly outlined in the alert box). If the first two items in the alert’s item list
  13010. are the OK button and the Cancel button, respectively, 0 will refer to the OK button
  13011. and 1 to the Cancel button. The reason for this is that the value of boldItm plus 1
  13012. is interpreted as an item number, and normally items 1 and 2 are the OK and Cancel
  13013. buttons, respectively. Whatever the item having the corresponding item number happens
  13014. to be, a bold rounded-corner rectangle will be drawn outside its display rectangle.
  13015.  
  13016. Note:  When deciding where to place items in an alert box, be sure to allow
  13017.        room for any bold outlines that may be drawn.
  13018.  
  13019. The boxDrwn field is TRUE if the alert box is to be drawn.
  13020.  
  13021. The sound field specifies which sound should be emitted at this stage of the alert,
  13022. with a number from 0 to 3 that’s passed to the current sound procedure. You can call
  13023. ErrorSound to specify your own sound procedure; if you don’t, the standard sound
  13024. procedure will be used (as described earlier in the “Alerts” section).
  13025.  
  13026. You access the alert template by converting the handle returned by the Resource
  13027. Manager to a template handle:
  13028.  
  13029. TYPE  AlertTHndl = ^AlertTPtr;
  13030.       AlertTPtr  = ^AlertTemplate;
  13031.  
  13032. Assembly-language note:  Rather than offsets into the fields of the StageList
  13033.                          data structure, there are masks for accessing the
  13034.                          information stored for an alert stage in a stages
  13035.                          word; they’re listed in the summary at the end of
  13036.                          this chapter.
  13037.  
  13038. æKY DialogPtr
  13039. æFc Dialogs.h
  13040. æT typedef
  13041. æD typedef WindowPtr DialogPtr;
  13042. æC 
  13043. »Dialog Pointers
  13044.  
  13045. There are two types of dialog pointer, DialogPtr and DialogPeek, analogous to the
  13046. window pointer types WindowPtr and WindowPeek. Most programmers will only need to use
  13047. DialogPtr.
  13048.  
  13049. The Dialog Manager defines the following type of dialog pointer:
  13050.  
  13051. TYPE  DialogPtr = WindowPtr;
  13052.  
  13053. It can do this because the first field of a dialog record contains the window record
  13054. for the dialog window. This type of pointer can be used to access fields of the
  13055. window record or can be passed to Window Manager routines that expect window pointers
  13056. as parameters. Since the WindowPtr data type is itself defined as GrafPtr, this type
  13057. of dialog pointer can also be used to access fields of the dialog window’s grafPort
  13058. or passed to QuickDraw routines that expect pointers to grafPorts as parameters.
  13059.  
  13060. For programmers who want to access dialog record fields beyond the window record, the
  13061. Dialog Manager also defines the following type of dialog pointer:
  13062.  
  13063. TYPE  DialogPeek = ^DialogRecord;
  13064.  
  13065. Assembly-language note:  From assembly language, of course, there’s no
  13066.                          type checking on pointers, and the two types
  13067.                          of pointer are equal.
  13068.  
  13069. _______________________________________________________________________________
  13070.  
  13071. »The DialogRecord Data Type
  13072.  
  13073. For those who want to know more about the data structure of a dialog record, the
  13074. exact structure is given here.
  13075.  
  13076. TYPE  DialogRecord = RECORD
  13077.                        window:     WindowRecord;  {dialog window}
  13078.                        items:      Handle;        {item list}
  13079.                        textH:      TEHandle;      {current editText item}
  13080.                        editField:  INTEGER;       {editText item number minus 1}
  13081.                        editOpen:   INTEGER;       {used internally}
  13082.                        aDefItem:   INTEGER        {default button item number}
  13083.                      END;
  13084.  
  13085. The window field contains the window record for the dialog window. The items field
  13086. contains a handle to the item list used for the dialog. (Remember that after reading
  13087. an item list from a resource file, the Dialog Manager makes a copy of it and uses
  13088. that copy.)
  13089.  
  13090. Note:  To get or change information about an item in a dialog, you pass the
  13091.        dialog pointer and the item number to a Dialog Manager procedure.
  13092.        You’ll never access information directly through the handle to the
  13093.        item list.
  13094.  
  13095. The Dialog Manager uses the next three fields when there are one or more editText
  13096. items in the dialog. If there’s more than one such item, these fields apply to the
  13097. one that currently is selected or displays the insertion point. The textH field
  13098. contains the handle to the edit record used by TextEdit. EditField is 1 less than the
  13099. item number of the current editText item, or –1 if there’s no editText item in the
  13100. dialog. The editOpen field is used internally by the Dialog Manager.
  13101.  
  13102. Note:  Actually, a single edit record is shared by all editText items; any
  13103.        changes you make to it will apply to all such items. See the TextEdit
  13104.        chapter for details about what kinds of changes you can make.
  13105.  
  13106. The aDefItem field is used for modal dialogs and alerts, which are treated internally
  13107. as special modal dialogs. It contains the item number of the default button. The
  13108. default button for a modal dialog is the first item in the item list, so this field
  13109. contains 1 for modal dialogs. The default button for an alert is specified in the
  13110. alert template; see the following section for more information.
  13111.  
  13112. _______________________________________________________________________________
  13113.  
  13114. »THE DRAWING ENVIRONMENT:  GRAFPORT
  13115. _______________________________________________________________________________
  13116.  
  13117. A grafPort is a complete drawing environment that defines where and how graphic
  13118. operations will take place. You can have many grafPorts open at once, and each one
  13119. will have its own coordinate system, drawing pattern, background pattern, pen size
  13120. and location, character font and style, and bit map in which drawing takes place. You
  13121. can instantly switch from one port to another. GrafPorts are the structures upon
  13122. which a program builds windows, which are fundamental to the Macintosh “overlapping
  13123. windows” user interface. Besides being used for windows on the screen, grafPorts are
  13124. used for printing and for off-screen drawing.
  13125.  
  13126. A grafPort is defined as follows:
  13127.  
  13128. TYPE  GrafPtr   =  ^GrafPort;
  13129.       GrafPort  =  RECORD
  13130.                      device:      INTEGER;    {device-specific information}
  13131.                      portBits:    BitMap;     {grafPort's bit map}
  13132.                      portRect:    Rect;       {grafPort's rectangle}
  13133.                      visRgn:      RgnHandle;  {visible region}
  13134.                      clipRgn:     RgnHandle;  {clipping region}
  13135.                      bkPat:       Pattern;    {background pattern}
  13136.                      fillPat:     Pattern;    {fill pattern}
  13137.                      pnLoc:       Point;      {pen location}
  13138.                      pnSize:      Point;      {pen size}
  13139.                      pnMode:      INTEGER;    {pen's transfer mode}
  13140.                      pnPat:       Pattern;    {pen pattern}
  13141.                      pnVis:       INTEGER;    {pen visibility}
  13142.                      txFont:      INTEGER;    {font number for text}
  13143.                      txFace:      Style;      {text's character style}
  13144.                      txMode:      INTEGER;    {text's transfer mode}
  13145.                      txSize:      INTEGER;    {font size for text}
  13146.                      spExtra:     Fixed;      {extra space}
  13147.                      fgColor:     LONGINT;    {foreground color}
  13148.                      bkColor:     LONGINT;    {background color}
  13149.                      colrBit:     INTEGER;    {color bit}
  13150.                      patStretch:  INTEGER;    {used internally}
  13151.                      picSave:     Handle;     {picture being saved}
  13152.                      rgnSave:     Handle;     {region being saved}
  13153.                      polySave:    Handle;     {polygon being saved}
  13154.                      grafProcs:   QDProcsPtr  {low-level drawing routines}
  13155.                    END;
  13156.  
  13157. Note that picSave is a Handle used internally by QuickDraw while it is saving a
  13158. picture, and rgnSave and polySave are used by QuickDraw as flags; they are set to “1”
  13159. when the corresponding action is taking place.
  13160.  
  13161. All QuickDraw operations refer to grafPorts via grafPtrs. (For historical reasons,
  13162. grafPort is one of the few objects in the Macintosh system software that’s referred
  13163. to by a pointer rather than a handle.)
  13164.  
  13165. Warning:  You can access all fields and subfields of a grafPort normally,
  13166.           but you should not store new values directly into them. QuickDraw
  13167.           has routines for altering all fields of a grafPort, and using
  13168.           these routines ensures that changing a grafPort produces no
  13169.           unusual side effects.
  13170.  
  13171. The device field of a grafPort contains device-specific information that’s used by
  13172. the Font Manager to achieve the best possible results when drawing text in the grafPort.
  13173. There may be physical differences in the same logical font for different output
  13174. devices, to ensure the highest-quality printing on the device being used. The default
  13175. value of the device field is 0, for best results on output to the screen. For more
  13176. information, see the Font Manager chapter.
  13177.  
  13178. The portBits field is the bit map that points to the bit image to be used by the
  13179. grafPort. The default bit map uses the entire screen as its bit image. The bit map
  13180. may be changed to indicate a different structure in memory:  All graphics routines
  13181. work in exactly the same way regardless of whether their effects are visible on the
  13182. screen. A program can, for example, prepare an image to be printed on a printer
  13183. without ever displaying the image on the screen, or develop a picture in an off-screen
  13184. bit map before transferring it to the screen. The portBits.bounds rectangle determines
  13185. the coordinate system of the grafPort; all other coordinates in the grafPort are
  13186. expressed in this system.
  13187.  
  13188. The portRect field is a rectangle that defines a subset of the bit map that will be
  13189. used for drawing:  All drawing done by the application occurs inside the portRect.
  13190. Its coordinates are in the coordinate system defined by the portBits.bounds rectangle.
  13191. The portRect usually falls within the portBits.bounds rectangle, but it’s not required
  13192. to do so. The portRect usually defines the “writable” interior area of a window,
  13193. document, or other object on the screen.
  13194.  
  13195. The visRgn field is manipulated by the Window Manager; you will normally never change
  13196. a grafPort’s visRgn. It indicates the region of the grafPort that’s actually visible
  13197. on the screen, that is, the part of the window that’s not covered by other windows.
  13198. For example, if you move one window in front of another, the Window Manager logically
  13199. removes the area of overlap from the visRgn of the window in back. When you draw into
  13200. the back window, whatever’s being drawn is clipped to the visRgn so that it doesn’t
  13201. run over onto the front window. The default visRgn is set to the portRect.
  13202.  
  13203. The clipRgn is the grafPort’s clipping region, an arbitrary region that you can use
  13204. to limit drawing to any region within the portRect. If, for example, you want to draw
  13205. a half circle on the screen, you can set the clipRgn to half the square that would
  13206. enclose the whole circle, and then draw the whole circle. Only the half within the
  13207. clipRgn will actually be drawn in the grafPort. The default clipRgn is set arbitrarily
  13208. large, you have full control over its setting; as a matter of recommended programming
  13209. practice, it is advisable to make the default clipRgn rectangle smaller.
  13210.  
  13211. Figure 10 illustrates a typical bit map (as defined by portBits), portRect, visRgn,
  13212. and clipRgn.
  13213.  
  13214. •••Refer to Figure 10.•••
  13215.  
  13216. Figure 10–GrafPort Regions
  13217.  
  13218. The bkPat and fillPat fields of a grafPort contain patterns used by certain QuickDraw
  13219. routines. BkPat is the “background” pattern that’s used when an area is erased or
  13220. when bits are scrolled out of it. When asked to fill an area with a specified pattern,
  13221. QuickDraw stores the given pattern in the fillPat field and then calls a low-level
  13222. drawing routine that gets the pattern from that field. The various graphic operations
  13223. are discussed in detail later in the descriptions of individual QuickDraw routines.
  13224.  
  13225. Of the next ten fields, the first five determine characteristics of the graphics pen
  13226. and the last five determine characteristics of any text that may be drawn; these are
  13227. described in separate sections below.
  13228.  
  13229. The fgColor, bkColor, and colrBit fields contain values related to drawing in color.
  13230. FgColor is the grafPort’s foreground color and bkColor is its background color.
  13231. ColrBit tells the color imaging software which plane of the color picture to draw
  13232. into. For more information, see “Drawing in Color” in the section “General Discussion
  13233. of Drawing”.
  13234.  
  13235. The patStretch field is used during output to a printer to expand patterns if necessary.
  13236. The application should not change its value.
  13237.  
  13238. The picSave, rgnSave, and polySave fields reflect the state of picture, region, and
  13239. polygon definition, respectively. The application shouldn’t be concerned about exactly
  13240. what information the handle, if any, leads to; you may, however, save the current
  13241. value of rgnSave, set the field to NIL to disable the region definition, and later
  13242. restore it to the saved value to resume the region definition. The picSave and polySave
  13243. fields work similarly for pictures and polygons.
  13244.  
  13245. Finally, the grafProcs field may point to a special data structure that the application
  13246. stores into if it wants to customize QuickDraw drawing routines or use QuickDraw in
  13247. other advanced, highly specialized ways (see “Customizing QuickDraw Operations”). If
  13248. grafProcs is NIL, QuickDraw responds in the standard ways described in this chapter.
  13249.  
  13250. _______________________________________________________________________________
  13251.  
  13252. »Pen Characteristics
  13253.  
  13254. The pnLoc, pnSize, pnMode, pnPat, and pnVis fields of a grafPort deal with the graphics
  13255. “pen”. Each grafPort has one and only one such pen, which is used for drawing lines,
  13256. shapes, and text. The pen has four characteristics:  a location, a size (height and
  13257. width), a drawing mode, and a drawing pattern (see Figure
  13258. 11).
  13259.  
  13260. •••Refer to Figure 11.•••
  13261.  
  13262. Figure 11–A Graphics Pen
  13263.  
  13264. The pnLoc field specifies the point where QuickDraw will begin drawing the next line,
  13265. shape, or character. It can be anywhere on the coordinate plane:  There are no restrictions
  13266. on the movement or placement of the pen. Remember that the pen location is a point in
  13267. the grafPort’s coordinate system, not a pixel in a bit image. The top left corner of
  13268. the pen is at the pen location; the pen hangs below and to the right of this point.
  13269.  
  13270. The pen is rectangular in shape, and its width and height are specified by pnSize.
  13271. The default size is a 1-by-1-bit square; the width and height can range from (0,0) to
  13272. (30000,30000). If either the pen width or the pen height is less than 1, the pen will
  13273. not draw.
  13274.  
  13275. The pnMode and pnPat fields of a grafPort determine how the bits under the pen are
  13276. affected when lines or shapes are drawn. The pnPat is a pattern that’s used like the
  13277. “ink” in the pen. This pattern, like all other patterns drawn in the grafPort, is
  13278. always aligned with the port’s coordinate system:  The top left corner of the pattern
  13279. is aligned with the top left corner of the portRect, so that adjacent areas of the
  13280. same pattern will blend into a continuous, coordinated pattern.
  13281.  
  13282. The pnMode field determines how the pen pattern is to affect what’s already in the
  13283. bit image when lines or shapes are drawn. When the pen draws, QuickDraw first determines
  13284. what bits in the bit image will be affected and finds their corresponding bits in the
  13285. pattern. It then does a bit-by-bit comparison based on the pen mode, which specifies
  13286. one of eight Boolean operations to perform. The resulting bit is stored into its
  13287. proper place in the bit image. The pen modes are described under “Transfer Modes” in
  13288. the section “General Discussion of Drawing”.
  13289.  
  13290. The pnVis field determines the pen’s visibility, that is, whether it draws on the
  13291. screen. For more information, see the descriptions of HidePen and ShowPen under “Pen
  13292. and Line-Drawing Routines” in the “QuickDraw Routines” section.
  13293.  
  13294. _______________________________________________________________________________
  13295.  
  13296. »Text Characteristics
  13297.  
  13298. The txFont, txFace, txMode, txSize, and spExtra fields of a grafPort determine how
  13299. text will be drawn—the font, style, and size of characters and how they will be
  13300. placed in the bit image. QuickDraw can draw characters as quickly and easily as it
  13301. draws lines and shapes, and in many prepared fonts. Font means the complete set of
  13302. characters of one typeface. The characters may be drawn in any size and character
  13303. style (that is, with stylistic variations such as bold, italic, and underline).
  13304. Figure 12 shows two characters drawn by QuickDraw and some terms associated with
  13305. drawing text.
  13306.  
  13307. •••Refer to Figure 12.•••
  13308.  
  13309. Figure 12–QuickDraw Characters
  13310.  
  13311. Text is drawn with the base line positioned at the pen location.
  13312.  
  13313. The txFont field is a font number that identifies the character font to be used in
  13314. the grafPort. The font number 0 represents the system font. For more information
  13315. about the system font, the other font numbers recognized by the Font Manager, and the
  13316. construction, layout, and loading of fonts, see the Font Manager chapter.
  13317.  
  13318. A character font is defined as a collection of images that make up the individual
  13319. characters of the font. The characters can be of unequal widths, and they’re not
  13320. restricted to their “cells”:  The lower curl of a lowercase j, for example, can
  13321. stretch back under the previous character (typographers call this kerning). A font
  13322. can consist of up to 255 distinct characters, yet not all characters need to be
  13323. defined in a single font. In addition, each font contains a missing symbol to be
  13324. drawn in case of a request to draw a character that’s missing from the font.
  13325.  
  13326. The txFace field controls the character style of the text with values from the set
  13327. defined by the Style data type:
  13328.  
  13329. TYPE  StyleItem  = (bold,italic,underline,outline,shadow,condense,extend);
  13330.       Style      = SET OF StyleItem;
  13331.  
  13332. Assembly-language note:  In assembly language, this set is stored as a word
  13333.                          whose low-order byte contains bits representing the
  13334.                          style. The bit numbers are specified by the following
  13335.                          global constants:
  13336.  
  13337.                            boldBit       .EQU    0
  13338.                            italicBit     .EQU    1
  13339.                            ulineBit      .EQU    2
  13340.                            outlineBit    .EQU    3
  13341.                            shadowBit     .EQU    5
  13342.                            extendBit     .EQU    6
  13343.  
  13344.                          If all bits are 0, it represents the plain character
  13345.                          style.
  13346.  
  13347. You can apply stylistic variations either alone or in combination; Figure 13 illustrates
  13348. some as applied to the Geneva font. Most combinations usually look good only for
  13349. large font sizes.
  13350.  
  13351. •••Refer to Figure 13.•••
  13352.  
  13353. Figure 13–Stylistic Variations
  13354.  
  13355. If you specify bold, each character is repeatedly drawn one bit to the right an
  13356. appropriate number of times for extra thickness.
  13357.  
  13358. Italic adds an italic slant to the characters. Character bits above the base line are
  13359. skewed right; bits below the base line are skewed left.
  13360.  
  13361. Underline draws a line below the base line of the characters. If part of a character
  13362. descends below the base line (as “y” in Figure 13), the underline
  13363. isn’t drawn through the pixel on either side of the descending part.
  13364.  
  13365. Outline makes a hollow, outlined character rather than a solid one. Shadow also makes
  13366. an outlined character, but the outline is thickened below and to the right of the
  13367. character to achieve the effect of a shadow. If you specify bold along with outline
  13368. or shadow, the hollow part of the character is widened.
  13369.  
  13370. Condense and extend affect the horizontal distance between all characters, including
  13371. spaces. Condense decreases the distance between characters and extend increases it,
  13372. by an amount that the Font Manager determines is appropriate.
  13373.  
  13374. The txMode field controls the way characters are placed in the bit image. It functions
  13375. much like a pnMode:  When a character is drawn, QuickDraw determines which bits in
  13376. the bit image will be affected, does a bit-by-bit comparison based on the mode, and
  13377. stores the resulting bits into the bit image. These modes are described under “Transfer
  13378. Modes” in the section “General Discussion of Drawing”. Only three of them—srcOr,
  13379. srcXor, and srcBic—should be used for drawing text.
  13380.  
  13381. Note:  If you use scrCopy, some extra blank space will be appended at the
  13382.        end of the text.
  13383.  
  13384. The txSize field specifies the font size in points (where “point” is a typographical
  13385. term meaning approximately 1/72 inch). Any size from 1 to 127 points may be specified.
  13386. If the Font Manager doesn’t have the font in a specified size, it will scale a size
  13387. it does have as necessary to produce the size desired. A value of 0 in this field
  13388. represents the system font size (12 points).
  13389.  
  13390. Finally, the spExtra field is useful when a line of characters is to be drawn justified
  13391. such that it’s aligned with both a left and a right margin (sometimes called “full
  13392. justification”). SpExtra contains a fixed-point number equal to the average number of
  13393. pixels by which each space character should be widened to fill out the line. The
  13394. Fixed data type is described in the Macintosh Memory Management:  An Introduction
  13395. chapter.
  13396.  
  13397. _______________________________________________________________________________
  13398.  
  13399. »COORDINATES IN GRAFPORTS
  13400. _______________________________________________________________________________
  13401.  
  13402. Each grafPort has its own local coordinate system. All fields in the grafPort are
  13403. expressed in these coordinates, and all calculations and actions performed in QuickDraw
  13404. use the local coordinate system of the currently selected port.
  13405.  
  13406. Two things are important to remember:
  13407.  
  13408.   •  Each grafPort maps a portion of the coordinate plane into a similarly-
  13409.      sized portion of a bit image.
  13410.   •  The portBits.bounds rectangle defines the local coordinates for a grafPort.
  13411.  
  13412. The top left corner of portBits.bounds is always aligned around the first bit in the
  13413. bit image; the coordinates of that corner “anchor” a point on the grid to that bit in
  13414. the bit image. This forms a common reference point for multiple grafPorts that use
  13415. the same bit image (such as the screen); given a portBits.bounds rectangle for each
  13416. port, you know that their top left corners coincide.
  13417.  
  13418. The relationship between the portBits.bounds and portRect rectangles is very important:
  13419.  The portBits.bounds rectangle establishes a coordinate system for the port, and the
  13420. portRect rectangle indicates the section of the coordinate plane (and thus the bit
  13421. image) that will be used for drawing. The portRect usually falls inside the portBits.bounds
  13422. rectangle, but it’s not required to do so.
  13423.  
  13424. When a new grafPort is created, its bit map is set to point to the entire screen, and
  13425. both the portBits.bounds and the portRect are set to rectangles enclosing the screen.
  13426. The point (0,0) corresponds to the screen’s top left corner.
  13427.  
  13428. You can redefine the local coordinates of the top left corner of the grafPort’s
  13429. portRect, using the SetOrigin procedure. This offsets the coordinates of the grafPort’s
  13430. portBits.bounds rectangle, recalculating the coordinates of all points in the grafPort
  13431. to be relative to the new corner coordinates. For example, consider these procedure
  13432. calls:
  13433.  
  13434.   SetPort(gamePort);
  13435.   SetOrigin(90,80)
  13436.  
  13437. The call to SetPort sets the current grafPort to gamePort; the call to SetOrigin
  13438. changes the local coordinates of the top left corner of that port’s portRect to
  13439. (90,80) (see Figure 14).
  13440.  
  13441. •••Refer to Figure 14.•••
  13442.  
  13443. Figure 14–Changing Local Coordinates
  13444.  
  13445. This offsets the coordinates of the following elements:
  13446.  
  13447.   gamePort^.portBits.bounds
  13448.   gamePort^.portRect
  13449.   gamePort^.visRgn
  13450.  
  13451. These three elements are always kept “in sync”.
  13452.  
  13453. Notice that when the local coordinates of a grafPort are offset, the grafPort’s
  13454. clipRgn and pen location are not offset. A good way to think of it is that the port’s
  13455. structure “sticks” to the screen, while the document in the grafPort
  13456. (along with the pen and clipRgn) “sticks” to the coordinate system. For example, in
  13457. Figure 14, before SetOrigin, the visRgn and clipRgn are the same as the portRect.
  13458. After the SetOrigin call, the locations of portBits.bounds, portRect, and visRgn do
  13459. not change on the screen; their coordinates are simply offset. As always, the top
  13460. left corner of portBits.bounds remains “anchored” around the first bit in the bit
  13461. image (the first pixel on the screen); the image on the screen doesn’t move as a
  13462. result of SetOrigin. However, the pen location and clipRgn do move on the screen; the
  13463. top left corner of the clipRgn is still
  13464. (100,100), but this location has moved down and to the right, and the pen has similarly
  13465. moved.
  13466.  
  13467. If you’re moving, comparing, or otherwise dealing with mathematical items in different
  13468. grafPorts (for example, finding the intersection of two regions in two different
  13469. grafPorts), you must adjust to a common coordinate system before you perform the
  13470. operation. A QuickDraw procedure, LocalToGlobal, lets you convert a point’s local
  13471. coordinates to a global coordinate system where the top left corner of the bit image
  13472. is (0,0); by converting the various local coordinates to global coordinates, you can
  13473. compare and mix them with confidence. For more information, see the description of
  13474. LocaltoGlobal under “Calculations with Points” in the “QuickDraw Routines” section.
  13475.  
  13476. æKY ResumeProcPtr
  13477. æFc Dialogs.h
  13478. æT typedef
  13479. æD typedef pascal void (*ResumeProcPtr)(void);
  13480. æC 
  13481.  
  13482. æKY SoundProcPtr
  13483. æFc Dialogs.h
  13484. æT typedef
  13485. æD typedef pascal void (*SoundProcPtr)(void);
  13486. æC 
  13487.  
  13488. æKY DialogRecord
  13489. DialogPeek
  13490. æFc Dialogs.h
  13491. æT struct
  13492. æD struct DialogRecord {
  13493.     WindowRecord window;
  13494.     Handle items;
  13495.     TEHandle textH;
  13496.     short editField;
  13497.     short editOpen;
  13498.     short aDefItem;
  13499. };
  13500.  
  13501. typedef struct DialogRecord DialogRecord;
  13502. typedef DialogRecord *DialogPeek;
  13503.  
  13504. æC 
  13505.  
  13506. »The DialogRecord Data Type
  13507.  
  13508. For those who want to know more about the data structure of a dialog record, the
  13509. exact structure is given here.
  13510.  
  13511. TYPE  DialogRecord = RECORD
  13512.                        window:     WindowRecord;  {dialog window}
  13513.                        items:      Handle;        {item list}
  13514.                        textH:      TEHandle;      {current editText item}
  13515.                        editField:  INTEGER;       {editText item number minus 1}
  13516.                        editOpen:   INTEGER;       {used internally}
  13517.                        aDefItem:   INTEGER        {default button item number}
  13518.                      END;
  13519.  
  13520. The window field contains the window record for the dialog window. The items field
  13521. contains a handle to the item list used for the dialog. (Remember that after reading
  13522. an item list from a resource file, the Dialog Manager makes a copy of it and uses
  13523. that copy.)
  13524.  
  13525. Note:  To get or change information about an item in a dialog, you pass the
  13526.        dialog pointer and the item number to a Dialog Manager procedure.
  13527.        You’ll never access information directly through the handle to the
  13528.        item list.
  13529.  
  13530. The Dialog Manager uses the next three fields when there are one or more editText
  13531. items in the dialog. If there’s more than one such item, these fields apply to the
  13532. one that currently is selected or displays the insertion point. The textH field
  13533. contains the handle to the edit record used by TextEdit. EditField is 1 less than the
  13534. item number of the current editText item, or –1 if there’s no editText item in the
  13535. dialog. The editOpen field is used internally by the Dialog Manager.
  13536.  
  13537. Note:  Actually, a single edit record is shared by all editText items; any
  13538.        changes you make to it will apply to all such items. See the TextEdit
  13539.        chapter for details about what kinds of changes you can make.
  13540.  
  13541. The aDefItem field is used for modal dialogs and alerts, which are treated internally
  13542. as special modal dialogs. It contains the item number of the default button. The
  13543. default button for a modal dialog is the first item in the item list, so this field
  13544. contains 1 for modal dialogs. The default button for an alert is specified in the
  13545. alert template; see the following section for more information.
  13546.  
  13547. æKY DialogTemplate
  13548. DialogTPtr
  13549. DialogTHndl
  13550. æFc Dialogs.h
  13551. æT struct
  13552. æD struct DialogTemplate {
  13553.     Rect boundsRect;
  13554.     short procID;
  13555.     Boolean visible;
  13556.     Boolean filler1;
  13557.     Boolean goAwayFlag;
  13558.     Boolean filler2;
  13559.     long refCon;
  13560.     short itemsID;
  13561.     Str255 title;
  13562. };
  13563.  
  13564. typedef struct DialogTemplate DialogTemplate;
  13565. typedef DialogTemplate *DialogTPtr, **DialogTHndl;
  13566.  
  13567. æC 
  13568. »Dialog Templates in Memory
  13569.  
  13570. The data structure of a dialog template is as follows:
  13571.  
  13572. TYPE DialogTemplate = RECORD
  13573.                         boundsRect:  Rect;     {becomes window's portRect}
  13574.                         procID:      INTEGER;  {window definiton ID}
  13575.                         visible:     BOOLEAN;  {TRUE if visible}
  13576.                         filler1:     BOOLEAN;  {not used}
  13577.                         goAwayFlag:  BOOLEAN;  {TRUE if has go-away region}
  13578.                         filler2:     BOOLEAN;  {not used}
  13579.                         refCon:      LONGINT;  {window's reference value}
  13580.                         itemsID:     INTEGER;  {resource ID of item list}
  13581.                         title:       Str255    {window's title}
  13582.                       END;
  13583.  
  13584. The filler1 and filler2 fields are there because for historical reasons the goAwayFlag
  13585. and refCon fields have to begin on a word boundary. The itemsID field contains the
  13586. resource ID of the dialog’s item list. The other fields are the same as the parameters
  13587. of the same name in the NewDialog function; they provide information about the dialog
  13588. window.
  13589.  
  13590. You access the dialog template by converting the handle returned by the Resource
  13591. Manager to a template handle:
  13592.  
  13593. TYPE  DialogTHndl  = ^DialogTPtr;
  13594.       DialogTPtr   = ^DialogTemplate;
  13595.  
  13596. æKY AlertTemplate
  13597. AlertTPtr
  13598. AlertTHndl
  13599. æFc Dialogs.h
  13600. æT struct
  13601. æD struct AlertTemplate {
  13602.     Rect boundsRect;
  13603.     short itemsID;
  13604.     StageList stages;
  13605. };
  13606.  
  13607. typedef struct AlertTemplate AlertTemplate;
  13608. typedef AlertTemplate *AlertTPtr, **AlertTHndl;
  13609.  
  13610. æC 
  13611.  »Alert Templates in Memory
  13612.  
  13613. The data structure of an alert template is as follows:
  13614.  
  13615. TYPE AlertTemplate = RECORD
  13616.                        boundsRect:  Rect;      {becomes window's portRect}
  13617.                        itemsID:     INTEGER;   {resource ID of item list}
  13618.                        stages:      StageList  {alert stage information}
  13619.                      END;
  13620.  
  13621. BoundsRect is the rectangle that becomes the portRect of the window's grafPort. The
  13622. itemsID field contains the resource ID of the item list for the alert.
  13623.  
  13624. The information in the stages field determines exactly what should happen at each
  13625. stage of the alert. It's packed into a word that has the following structure:
  13626.  
  13627. TYPE StageList = PACKED RECORD
  13628.                    boldItm4:  0..1;     {default button item number minus 1}
  13629.                    boxDrwn4:  BOOLEAN;  {TRUE if alert box to be drawn}
  13630.                    sound4:    0..3      {sound number}
  13631.                    boldItm3:  0..1; 
  13632.                    boxDrwn3:  BOOLEAN; 
  13633.                    sound3:    0..3 
  13634.                    boldItm2:  0..1; 
  13635.                    boxDrwn2:  BOOLEAN; 
  13636.                    sound2:    0..3 
  13637.                    boldItm1:  0..1; 
  13638.                    boxDrwn1:  BOOLEAN; 
  13639.                    sound1:    0..3 
  13640.                  END;
  13641.  
  13642. Notice that the information is stored in reverse order—for the fourth stage first,
  13643. and for the first stage last.
  13644.  
  13645. The boldItm field indicates which button should be the default button (and therefore
  13646. boldly outlined in the alert box). If the first two items in the alert’s item list
  13647. are the OK button and the Cancel button, respectively, 0 will refer to the OK button
  13648. and 1 to the Cancel button. The reason for this is that the value of boldItm plus 1
  13649. is interpreted as an item number, and normally items 1 and 2 are the OK and Cancel
  13650. buttons, respectively. Whatever the item having the corresponding item number happens
  13651. to be, a bold rounded-corner rectangle will be drawn outside its display rectangle.
  13652.  
  13653. Note:  When deciding where to place items in an alert box, be sure to allow
  13654.        room for any bold outlines that may be drawn.
  13655.  
  13656. The boxDrwn field is TRUE if the alert box is to be drawn.
  13657.  
  13658. The sound field specifies which sound should be emitted at this stage of the alert,
  13659. with a number from 0 to 3 that’s passed to the current sound procedure. You can call
  13660. ErrorSound to specify your own sound procedure; if you don’t, the standard sound
  13661. procedure will be used (as described earlier in the “Alerts” section).
  13662.  
  13663. You access the alert template by converting the handle returned by the Resource
  13664. Manager to a template handle:
  13665.  
  13666. TYPE  AlertTHndl = ^AlertTPtr;
  13667.       AlertTPtr  = ^AlertTemplate;
  13668.  
  13669. Assembly-language note:  Rather than offsets into the fields of the StageList
  13670.                          data structure, there are masks for accessing the
  13671.                          information stored for an alert stage in a stages
  13672.                          word; they’re listed in the summary at the end of
  13673.                          this chapter.
  13674.  
  13675. æKY InitDialogs
  13676. æFc Dialogs.h
  13677. æT Function
  13678. æTN A97B
  13679. æD pascal void InitDialogs(ResumeProcPtr resumeProc)
  13680.     = 0xA97B; 
  13681. æDT InitDialogs((ResumeProcPtr) resumeProc);
  13682. æRI I-411, P-107, 112, 174
  13683. æC  
  13684. Call InitDialogs once before all other Dialog Manager routines, to initialize the
  13685. Dialog Manager. InitDialogs does the following initialization:
  13686.  
  13687.   •  It saves the pointer passed in resumeProc, if any, for access by the
  13688.      System Error Handler in case a fatal system error occurs. ResumeProc
  13689.      can be a pointer to a resume procedure, as described in the System
  13690.      Error Handler chapter, or NIL if no such procedure is desired.
  13691.  
  13692. Assembly-language note:  InitDialogs stores the address of the resume
  13693.                          procedure in a global variable named ResumeProc.
  13694.  
  13695.   •  It installs the standard sound procedure.
  13696.   •  It passes empty strings to ParamText.
  13697.  
  13698. æKY ErrorSound
  13699. æFc Dialogs.h
  13700. æT Function
  13701. æTN A98C
  13702. æD pascal void ErrorSound(SoundProcPtr soundProc)
  13703.     = 0xA98C; 
  13704. æDT ErrorSound((SoundProcPtr) soundProc);
  13705. æRI I-411
  13706. æC  
  13707. ErrorSound sets the sound procedure for alerts to the procedure pointed to by soundProc;
  13708. if you don’t call ErrorSound, the Dialog Manager uses the standard sound procedure.
  13709. (For details, see the “Alerts” section.) If you pass NIL for soundProc, there will be
  13710. no sound (or menu bar blinking) at all.
  13711.  
  13712. Assembly-language note:  The address of the sound procedure being used is
  13713.                          stored in the global variable DABeeper.
  13714.  
  13715. æKY NewDialog
  13716. æFc Dialogs.h
  13717. æT Function
  13718. æTN A97D
  13719. æD pascal DialogPtr NewDialog(Ptr wStorage,const Rect *boundsRect,const Str255 title,
  13720.     Boolean visible,short procID,WindowPtr behind,Boolean goAwayFlag,long refCon,
  13721.     Handle itmLstHndl)
  13722.     = 0xA97D; 
  13723. æDT DialogPtr myVariable = NewDialog((Ptr) wStorage,(const Rect *) boundsRect,(const Str255) title,()
  13724.     Boolean visible,(short) procID,(WindowPtr) behind,(Boolean) goAwayFlag,(long) refCon,()
  13725.     Handle itmLstHndl);
  13726. æMM
  13727. æRI I-412, P-107, 177
  13728. æC 
  13729. NewDialog creates a dialog as specified by its parameters and returns a pointer to
  13730. the new dialog. The first eight parameters (dStorage through refCon) are passed to
  13731. the Window Manager function NewWindow, which creates the dialog window; the meanings
  13732. of these parameters are summarized below. The items parameter is a handle to the
  13733. dialog’s item list. You can get the items handle by calling the Resource Manager to
  13734. read the item list from the resource file into memory.
  13735.  
  13736. Note:  Advanced programmers can create their own item lists in memory rather
  13737.        than have them read from a resource file. The exact format is given
  13738.        later under “Formats of Resources for Dialogs and Alerts”.
  13739.  
  13740. DStorage is analogous to the wStorage parameter of NewWindow; it’s a pointer to the
  13741. storage to use for the dialog record. If you pass NIL for dStorage, the dialog record
  13742. will be allocated in the heap (which, in the case of modeless dialogs, may cause the
  13743. heap to become fragmented).
  13744.  
  13745. BoundsRect, a rectangle given in global coordinates, determines the dialog window’s
  13746. size and location. It becomes the portRect of the window’s grafPort. Remember that
  13747. the top coordinate of this rectangle should be at least 25 points below the top of
  13748. the screen for a modal dialog, to allow for the menu bar and the border around the
  13749. portRect, and at least 40 points below the top of the screen for a modeless dialog,
  13750. to allow for the menu bar and the window’s title bar.
  13751.  
  13752. Title is the title of a modeless dialog box; pass the empty string for modal dialogs.
  13753.  
  13754. If the visible parameter is TRUE, the dialog window is drawn on the screen. If it’s
  13755. FALSE, the window is initially invisible and may later be shown with a call to the
  13756. Window Manager procedure ShowWindow.
  13757.  
  13758. Note:  NewDialog generates an update event for the entire window contents,
  13759.        so the items aren’t drawn immediately, with the exception of controls.
  13760.        The Dialog Manager calls the Control Manager to draw controls, and the
  13761.        Control Manager draws them immediately rather than via the standard
  13762.        update mechanism. Because of this, the Dialog Manager calls the Window
  13763.        Manager procedure ValidRect for the enclosing rectangle of each control,
  13764.        so the controls won’t be drawn twice. If you find that the other items
  13765.        aren’t being drawn soon enough after the controls, try making the
  13766.        window invisible initially and then calling ShowWindow to show it.
  13767.  
  13768. ProcID is the window definition ID, which leads to the window definition function for
  13769. this type of window. The window definition IDs for the standard types of dialog
  13770. window are dBoxProc for the modal type and documentProc for the modeless type.
  13771.  
  13772. The behind parameter specifies the window behind which the dialog window is to be
  13773. placed on the desktop. Pass POINTER(–1) to bring up the dialog window in front of all
  13774. other windows.
  13775.  
  13776. GoAwayFlag applies to modeless dialog boxes; if it’s TRUE, the dialog window has a
  13777. close box in its title bar when the window is active.
  13778.  
  13779. RefCon is the dialog window’s reference value, which the application may store into
  13780. and access for any purpose.
  13781.  
  13782. NewDialog sets the font of the dialog window’s grafPort to the system font or, if you
  13783. previously called SetDAFont, to the specified font. It also sets the window class in
  13784. the window record to dialogKind.
  13785.  
  13786. æKY newdialog
  13787. æFc Dialogs.h
  13788. æT Function
  13789. æTN A97D
  13790. æD DialogPtr newdialog(Ptr wStorage,const Rect *boundsRect,char *title,Boolean visible,
  13791.     short procID,WindowPtr behind,Boolean goAwayFlag,long refCon,Handle itmLstHndl); 
  13792. æDT DialogPtr myVariable = newdialog((Ptr) wStorage,(const Rect *) boundsRect,(char *) title,(Boolean) visible,()
  13793.     short procID,(WindowPtr) behind,(Boolean) goAwayFlag,(long) refCon,(Handle) itmLstHndl);
  13794. æMM
  13795. æRI I-412, P-107, 177
  13796. æC 
  13797. NewDialog creates a dialog as specified by its parameters and returns a pointer to
  13798. the new dialog. The first eight parameters (dStorage through refCon) are passed to
  13799. the Window Manager function NewWindow, which creates the dialog window; the meanings
  13800. of these parameters are summarized below. The items parameter is a handle to the
  13801. dialog’s item list. You can get the items handle by calling the Resource Manager to
  13802. read the item list from the resource file into memory.
  13803.  
  13804. Note:  Advanced programmers can create their own item lists in memory rather
  13805.        than have them read from a resource file. The exact format is given
  13806.        later under “Formats of Resources for Dialogs and Alerts”.
  13807.  
  13808. DStorage is analogous to the wStorage parameter of NewWindow; it’s a pointer to the
  13809. storage to use for the dialog record. If you pass NIL for dStorage, the dialog record
  13810. will be allocated in the heap (which, in the case of modeless dialogs, may cause the
  13811. heap to become fragmented).
  13812.  
  13813. BoundsRect, a rectangle given in global coordinates, determines the dialog window’s
  13814. size and location. It becomes the portRect of the window’s grafPort. Remember that
  13815. the top coordinate of this rectangle should be at least 25 points below the top of
  13816. the screen for a modal dialog, to allow for the menu bar and the border around the
  13817. portRect, and at least 40 points below the top of the screen for a modeless dialog,
  13818. to allow for the menu bar and the window’s title bar.
  13819.  
  13820. Title is the title of a modeless dialog box; pass the empty string for modal dialogs.
  13821.  
  13822. If the visible parameter is TRUE, the dialog window is drawn on the screen. If it’s
  13823. FALSE, the window is initially invisible and may later be shown with a call to the
  13824. Window Manager procedure ShowWindow.
  13825.  
  13826. Note:  NewDialog generates an update event for the entire window contents,
  13827.        so the items aren’t drawn immediately, with the exception of controls.
  13828.        The Dialog Manager calls the Control Manager to draw controls, and the
  13829.        Control Manager draws them immediately rather than via the standard
  13830.        update mechanism. Because of this, the Dialog Manager calls the Window
  13831.        Manager procedure ValidRect for the enclosing rectangle of each control,
  13832.        so the controls won’t be drawn twice. If you find that the other items
  13833.        aren’t being drawn soon enough after the controls, try making the
  13834.        window invisible initially and then calling ShowWindow to show it.
  13835.  
  13836. ProcID is the window definition ID, which leads to the window definition function for
  13837. this type of window. The window definition IDs for the standard types of dialog
  13838. window are dBoxProc for the modal type and documentProc for the modeless type.
  13839.  
  13840. The behind parameter specifies the window behind which the dialog window is to be
  13841. placed on the desktop. Pass POINTER(–1) to bring up the dialog window in front of all
  13842. other windows.
  13843.  
  13844. GoAwayFlag applies to modeless dialog boxes; if it’s TRUE, the dialog window has a
  13845. close box in its title bar when the window is active.
  13846.  
  13847. RefCon is the dialog window’s reference value, which the application may store into
  13848. and access for any purpose.
  13849.  
  13850. NewDialog sets the font of the dialog window’s grafPort to the system font or, if you
  13851. previously called SetDAFont, to the specified font. It also sets the window class in
  13852. the window record to dialogKind.
  13853.  
  13854. æKY GetNewDialog
  13855. æFc Dialogs.h
  13856. æT Function
  13857. æTN A97C
  13858. æD pascal DialogPtr GetNewDialog(short dialogID,Ptr dStorage,WindowPtr behind)
  13859.     = 0xA97C; 
  13860. æDT DialogPtr myVariable = GetNewDialog((short) dialogID,(Ptr) dStorage,(WindowPtr) behind);
  13861. æMM
  13862. æRT 4,34
  13863. æRI I-413, V-284, N4-1,  P-107, 172
  13864. æC 
  13865. Like NewDialog (above), GetNewDialog creates a dialog as specified by its parameters
  13866. and returns a pointer to the new dialog. Instead of having the parameters boundsRect,
  13867. title, visible, procID, goAwayFlag, and refCon, GetNewDialog has a single dialogID
  13868. parameter, where dialogID is the resource ID of a dialog template that supplies the
  13869. same information as those parameters. The dialog template also contains the resource
  13870. ID of the dialog’s item list. After calling the Resource Manager to read the item
  13871. list into memory (if it’s not already in memory), GetNewDialog makes a copy of the
  13872. item list and uses that copy; thus you may have multiple independent dialogs whose
  13873. items have the same types, locations, and initial contents. The dStorage and behind
  13874. parameters of GetNewDialog have the same meaning as in NewDialog.
  13875.  
  13876. Warning:  If either the dialog template resource or the item list
  13877.           resource can’t be read, the function result is undefined.
  13878.  
  13879. Note:  GetNewDialog doesn’t release the memory occupied by the resources.
  13880.  
  13881. The GetNewDialog routine will attempt to load a 'dctb' resource and returns a pointer
  13882. to a color grafPort if the resource exists. If no 'dctb' resource is present, GetNewDialog
  13883. returns a pointer to an old grafPort.
  13884.  
  13885. The dialog color table is copied before it is passed to SetWinSize unless its ctSize
  13886. field is equal to –1, indicating that the default window colors are to be used instead.
  13887. The copy is made so that the color table resource can be purged without affecting the
  13888. dialog.
  13889.  
  13890. The color dialog item list resource is duplicated as well, so it can be purgeable.
  13891.  
  13892. æKY CloseDialog
  13893. æFc Dialogs.h
  13894. æT Function
  13895. æTN A982
  13896. æD pascal void CloseDialog(DialogPtr theDialog)
  13897.     = 0xA982; 
  13898. æDT CloseDialog((DialogPtr) theDialog);
  13899. æMM
  13900. æRI I-413, P-107, 167
  13901. æC 
  13902. CloseDialog removes theDialog’s window from the screen and deletes it from the window
  13903. list, just as when the Window Manager procedure CloseWindow is called. It releases
  13904. the memory occupied by the following:
  13905.  
  13906.   •  The data structures associated with the dialog window (such as the
  13907.      window’s structure, content, and update regions).
  13908.   •  All the items in the dialog (except for pictures and icons, which
  13909.      might be shared resources), and any data structures associated with
  13910.      them. For example, it would dispose of the region occupied by the
  13911.      thumb of a scroll bar, or a similar region for some other control
  13912.      in the dialog.
  13913.  
  13914. CloseDialog does not dispose of the dialog record or the item list. Figure 10 illustrates
  13915. the effect of CloseDialog (and DisposDialog, described below).
  13916.  
  13917. •••Refer to Figure 10.•••
  13918.  
  13919. Figure 10–CloseDialog and DisposDialog
  13920.  
  13921. Call CloseDialog when you’re done with a dialog if you supplied NewDialog or GetNewDialog
  13922. with a pointer to the dialog storage (in the dStorage parameter) when you created the
  13923. dialog.
  13924.  
  13925. Note:  Even if you didn’t supply a pointer to the dialog storage, you may
  13926.        want to call CloseDialog if you created the dialog with NewDialog.
  13927.        You would call CloseDialog if you wanted to keep the item list around
  13928.        (since, unlike GetNewDialog, NewDialog does not use a copy of the
  13929.        item list).
  13930.  
  13931. æKY DisposDialog
  13932. æFc Dialogs.h
  13933. æT Function
  13934. æTN A983
  13935. æD pascal void DisposDialog(DialogPtr theDialog)
  13936.     = 0xA983; 
  13937. æDT DisposDialog((DialogPtr) theDialog);
  13938. æRI I-415
  13939. æC 
  13940. DisposDialog calls CloseDialog (above) and then releases the memory occupied by the
  13941. dialog’s item list and dialog record. Call DisposDialog when you’re done with a
  13942. dialog if you let the dialog record be allocated in the heap when you created the
  13943. dialog (by passing NIL as the dStorage parameter to NewDialog or GetNewDialog).
  13944.  
  13945. æKY CouldDialog
  13946. æFc Dialogs.h
  13947. æT Function
  13948. æTN A979
  13949. æD pascal void CouldDialog(short dialogID)
  13950.     = 0xA979; 
  13951. æDT CouldDialog((short) dialogID);
  13952. æMM
  13953. æRI I-415, V-284
  13954. æC 
  13955. CouldDialog makes the dialog template having the given resource ID unpurgeable
  13956. (reading it into memory if it’s not already there). It does the same for the dialog
  13957. window’s definition function, the dialog’s item list resource, and any items defined
  13958. as resources. This is useful if the dialog box may come up when the resource file
  13959. isn’t accessible, such as during a disk copy.
  13960.  
  13961. Warning:  CouldDialog assumes your dialogs use the system font; if you’ve
  13962.           changed the font with SetDAFont, calling CouldDialog doesn’t make
  13963.           the font unpurgeable.
  13964.  
  13965. The CouldDialog procedure makes the dialog color table template unpurgeable
  13966. (reading it into memory if it isn’t already there), if it exists. It does the same
  13967. for the dialog’s color item list, if it has one.
  13968.  
  13969. Warning:  CouldDialog doesn’t load or make 'FONT' or 'FOND' resources
  13970.           indicated in the color item list unpurgeable.
  13971.  
  13972. æKY FreeDialog
  13973. æFc Dialogs.h
  13974. æT Function
  13975. æTN A97A
  13976. æD pascal void FreeDialog(short dialogID)
  13977.     = 0xA97A; 
  13978. æDT FreeDialog((short) dialogID);
  13979. æMM
  13980. æRI I-415, V-284
  13981. æC 
  13982. Given the resource ID of a dialog template previously specified in a call to CouldDialog,
  13983. FreeDialog undoes the effect of CouldDialog (by making the resources purgeable). It
  13984. should be called when there’s no longer a need to keep the resources in memory.
  13985.  
  13986. Given the resource ID of a dialog template previously specified in a call to CouldDialog,
  13987. the FreeDialog routine undoes the effect of CouldDialog, by restoring the original
  13988. purge state of the color table and color item list resources.
  13989.  
  13990. æKY ParamText
  13991. æFc Dialogs.h
  13992. æT Function
  13993. æTN A98B
  13994. æD pascal void ParamText(const Str255 param0,const Str255 param1,const Str255 param2,
  13995.     const Str255 param3)
  13996.     = 0xA98B; 
  13997. æDT ParamText((const Str255) param0,(const Str255) param1,(const Str255) param2,(
  13998.     const) Str255 param3);
  13999. æMM
  14000. æRI I-421
  14001. æC  
  14002. ParamText provides a means of substituting text in statText items:  param0 through
  14003. param3 will replace the special strings '^0' through '^3' in all statText items in
  14004. all subsequent dialog or alert boxes. Pass empty strings for parameters not used.
  14005.  
  14006. Assembly-language note:  Assembly-language programmers may pass NIL for
  14007.                          parameters not used or for strings that are not
  14008.                          to be changed.
  14009.  
  14010. For example, if the text is defined as 'Cannot open document ^0' and docName is a
  14011. string variable containing a document name that the user typed, you can call ParamText(docName,'
  14012. ',' ',' ')
  14013.  
  14014. Note:  All strings that may need to be translated to other languages should
  14015.        be stored in resource files.
  14016.  
  14017. Assembly-language note:  The Dialog Manager stores handles to the four
  14018.                          ParamText parameters in a global array named DAStrings.
  14019.  
  14020. æKY ModalDialog
  14021. æFc Dialogs.h
  14022. æT Function
  14023. æTN A991
  14024. æD pascal void ModalDialog(ModalFilterProcPtr filterProc,short *itemHit)
  14025.     = 0xA991; 
  14026. æDT ModalDialog((ModalFilterProcPtr) filterProc,(short *) itemHit);
  14027. æMM
  14028. æRT 34, 203
  14029. æRI I-415, N34-2, 3,   P-108, 176
  14030. æC  
  14031. Call ModalDialog after creating a modal dialog and bringing up its window in the
  14032. frontmost plane. ModalDialog repeatedly gets and handles events in the dialog’s
  14033. window; after handling an event involving an enabled dialog item, it returns with the
  14034. item number in itemHit. Normally you’ll then do whatever is appropriate as a response
  14035. to an event in that item.
  14036.  
  14037. ModalDialog gets each event by calling the Toolbox Event Manager function GetNextEvent.
  14038. If the event is a mouse-down event outside the content region of the dialog window,
  14039. ModalDialog emits sound number 1 (which should be a single beep) and gets the next
  14040. event; otherwise, it filters and handles the event as described below.
  14041.  
  14042. Note:  Once before getting each event, ModalDialog calls SystemTask, a
  14043.        Desk Manager procedure that must be called regularly so that desk
  14044.        accessories will work properly.
  14045.  
  14046. The filterProc parameter determines how events are filtered. If it’s NIL, the standard
  14047. filterProc function is executed; this causes ModalDialog to return 1 in itemHit if
  14048. the Return key or Enter key is pressed. If filterProc isn’t NIL, ModalDialog filters
  14049. events by executing the function it points to. Your filterProc function should have
  14050. three parameters and return a Boolean value. For example, this is how it would be
  14051. declared if it were named MyFilter:
  14052.  
  14053. FUNCTION MyFilter (theDialog:  DialogPtr; VAR theEvent:  EventRecord;
  14054.                    VAR itemHit:  INTEGER) :  BOOLEAN;
  14055.  
  14056. A function result of FALSE tells ModalDialog to go ahead and handle the event, which
  14057. either can be sent through unchanged or can be changed to simulate a different event.
  14058. A function result of TRUE tells ModalDialog to return immediately rather than handle
  14059. the event; in this case, the filterProc function sets itemHit to the item number that
  14060. ModalDialog should return.
  14061.  
  14062. Note:  If you want it to be consistent with the standard filterProc function,
  14063.        your function should at least check whether the Return key or Enter
  14064.        key was pressed and, if so, return 1 in itemHit and a function result
  14065.        of TRUE.
  14066.  
  14067. You can use the filterProc function, for example, to treat a typed character in a
  14068. special way (such as ignore it, or make it have the same effect as another character
  14069. or as clicking a button); in this case, the function would test for a key-down event
  14070. with that character. As another example, suppose the dialog box contains a userItem
  14071. whose procedure draws a clock with the current time displayed. The filterProc function
  14072. can call that procedure and return FALSE without altering the current event.
  14073.  
  14074. Note:  ModalDialog calls GetNextEvent with a mask that excludes disk-inserted
  14075.        events. To receive disk-inserted events, your filterProc function can
  14076.        call GetNextEvent (or EventAvail) with a mask that accepts only that
  14077.        type of event.
  14078.  
  14079. ModalDialog handles the events for which the filterProc function returns FALSE as
  14080. follows:
  14081.  
  14082.   •  In response to an activate or update event for the dialog window,
  14083.      ModalDialog activates or updates the window.
  14084.   •  If the mouse button is pressed in an editText item, ModalDialog
  14085.      responds to the mouse activity as appropriate (displaying an insertion
  14086.      point or selecting text). If a key-down event occurs and there’s an
  14087.      editText item, text entry and editing are handled in the standard way
  14088.      for such items (except that if the Command key is down, ModalDialog
  14089.      responds as though it’s not). In either case, ModalDialog returns if
  14090.      the editText item is enabled or does nothing if it’s disabled. If a
  14091.      key-down event occurs when there’s no editText item, ModalDialog does
  14092.      nothing.
  14093.   •  If the mouse button is pressed in a control, ModalDialog calls the
  14094.      Control Manager function TrackControl. If the mouse button is released
  14095.      inside the control and the control is enabled, ModalDialog returns;
  14096.      otherwise, it does nothing.
  14097.   •  If the mouse button is pressed in any other enabled item in the
  14098.      dialog box, ModalDialog returns. If the mouse button is pressed in
  14099.      any other disabled item or in no item, or if any other event occurs,
  14100.      ModalDialog does nothing.
  14101.  
  14102. æKY IsDialogEvent
  14103. æFc Dialogs.h
  14104. æT Function
  14105. æTN A97F
  14106. æD pascal Boolean IsDialogEvent(const EventRecord *theEvent)
  14107.     = 0xA97F; 
  14108. æDT Boolean myVariable = IsDialogEvent((const EventRecord *) theEvent);
  14109. æRI I-416, N5-1, P-108, 175
  14110. æC  
  14111. If your application includes any modeless dialogs, call IsDialogEvent after calling
  14112. the Toolbox Event Manager function GetNextEvent.
  14113.  
  14114. Warning:  If your modeless dialog contains any editText items, you must call
  14115.           IsDialogEvent (and then DialogSelect) even if GetNextEvent returns
  14116.           FALSE; otherwise your dialog won’t receive null events and the
  14117.           caret won’t blink.
  14118.  
  14119. Pass the current event in theEvent. IsDialogEvent determines whether theEvent needs
  14120. to be handled as part of a dialog. If theEvent is an activate or update event for a
  14121. dialog window, a mouse-down event in the content region of an active dialog window,
  14122. or any other type of event when a dialog window is active, IsDialogEvent returns
  14123. TRUE; otherwise, it returns FALSE.
  14124.  
  14125. When FALSE is returned, just handle the event yourself like any other event that’s
  14126. not dialog-related. When TRUE is returned, you’ll generally end up passing the event
  14127. to DialogSelect for it to handle (as described below), but first you should do some
  14128. additional checking:
  14129.  
  14130.   •  DialogSelect doesn’t handle keyboard equivalents of commands. Check
  14131.      whether the event is a key-down event with the Command key held down
  14132.      and, if so, carry out the command if it’s one that applies when a
  14133.      dialog window is active. (If the command doesn’t so apply, do nothing.)
  14134.   •  In special cases, you may want to bypass DialogSelect or do some
  14135.      preprocessing before calling it. If so, check for those events and
  14136.      respond accordingly. You would need to do this, for example, if the
  14137.      dialog is to respond to disk-inserted events.
  14138.  
  14139. For cases other than these, pass the event to DialogSelect for it to handle.
  14140.  
  14141. æKY DialogSelect
  14142. æFc Dialogs.h
  14143. æT Function
  14144. æTN A980
  14145. æD pascal Boolean DialogSelect(const EventRecord *theEvent,DialogPtr *theDialog,
  14146.     short *itemHit)
  14147.     = 0xA980; 
  14148. æDT Boolean myVariable = DialogSelect((const EventRecord *) theEvent,(DialogPtr *) theDialog,(
  14149.     short) * itemHit);
  14150. æMM
  14151. æRT 34
  14152. æRI I-417, N34-3, P-108, 168
  14153. æC 
  14154. You’ll normally call DialogSelect when IsDialogEvent returns TRUE, passing in theEvent
  14155. an event that needs to be handled as part of a modeless dialog. DialogSelect handles
  14156. the event as described below. If the event involves an enabled dialog item, DialogSelect
  14157. returns a function result of TRUE with the dialog pointer in theDialog and the item
  14158. number in itemHit; otherwise, it returns FALSE with theDialog and itemHit undefined.
  14159. Normally when DialogSelect returns TRUE, you’ll do whatever is appropriate as a
  14160. response to the event, and when it returns FALSE you’ll do nothing.
  14161.  
  14162. If the event is an activate or update event for a dialog window, DialogSelect activates
  14163. or updates the window and returns FALSE.
  14164.  
  14165. If the event is a mouse-down event in an editText item, DialogSelect responds as
  14166. appropriate (displaying a caret at the insertion point or selecting text). If it’s a
  14167. key-down or auto-key event and there’s an editText item, text entry and editing are
  14168. handled in the standard way. In either case, DialogSelect returns TRUE if the editText
  14169. item is enabled or FALSE if it’s disabled. If a key-down or auto-key event is passed
  14170. when there’s no editText item, DialogSelect returns FALSE.
  14171.  
  14172. Note:  For a keyboard event, DialogSelect doesn’t check to see whether the
  14173.        Command key is held down; to handle keyboard equivalents of commands,
  14174.        you have to check for them before calling DialogSelect. Similarly, to
  14175.        treat a typed character in a special way (such as ignore it, or make
  14176.        it have the same effect as another character or as clicking a button),
  14177.        you need to check for a key-down event with that character before
  14178.        calling DialogSelect.
  14179.  
  14180. If the event is a mouse-down event in a control, DialogSelect calls the Control
  14181. Manager function TrackControl. If the mouse button is released inside the control and
  14182. the control is enabled, DialogSelect returns TRUE; otherwise, it returns FALSE.
  14183.  
  14184. If the event is a mouse-down event in any other enabled item, DialogSelect returns
  14185. TRUE. If it’s a mouse-down event in any other disabled item or in no item, or if it’s
  14186. any other event, DialogSelect returns FALSE.
  14187.  
  14188. Note:  If the event isn’t one that DialogSelect specifically checks for (if
  14189.        it’s a null event, for example), and there’s an editText item in the
  14190.        dialog, DialogSelect calls the TextEdit procedure TEIdle to make the
  14191.        caret blink.
  14192.  
  14193. æKY DrawDialog
  14194. æFc Dialogs.h
  14195. æT Function
  14196. æTN A981
  14197. æD pascal void DrawDialog(DialogPtr theDialog)
  14198.     = 0xA981; 
  14199. æDT DrawDialog((DialogPtr) theDialog);
  14200. æMM
  14201. æRI I-418
  14202. æC 
  14203. DrawDialog draws the contents of the given dialog box. Since DialogSelect and ModalDialog
  14204. handle dialog window updating, this procedure is useful only in unusual situations.
  14205. You would call it, for example, to display a dialog box that doesn’t require any
  14206. response but merely tells the user what’s going on during a time-consuming process.
  14207.  
  14208. æKY UpdtDialog
  14209. æFc Dialogs.h
  14210. æT Function
  14211. æTN A978
  14212. æD pascal void UpdtDialog(DialogPtr theDialog,RgnHandle updateRgn)
  14213.     = 0xA978; 
  14214. æDT UpdtDialog((DialogPtr) theDialog,(RgnHandle) updateRgn);
  14215. æMM
  14216. æRI IV-60
  14217. æC  
  14218. UpdtDialog is a faster version of the DrawDialog procedure. Instead of drawing the
  14219. entire contents of the given dialog box, UpdtDialog draws only the items that are in
  14220. a specified update region. UpdtDialog is called in response to an update event, and
  14221. is usually bracketed by calls to the Window Manager procedures BeginUpdate and EndUpdate.
  14222. UpdateRgn should be set to the visRgn of theWindow’s port. (For more details, see the
  14223. BeginUpdate procedure in the Window Manager chapter.)
  14224.  
  14225. æKY Alert
  14226. æFc Dialogs.h
  14227. æT Function
  14228. æTN A985
  14229. æD pascal short Alert(short alertID,ModalFilterProcPtr filterProc)
  14230.     = 0xA985; 
  14231. æDT short myVariable = Alert((short) alertID,(ModalFilterProcPtr) filterProc);
  14232. æMM
  14233. æRI I-418, V-284
  14234. æC 
  14235. This function invokes the alert defined by the alert template that has the given
  14236. resource ID. It calls the current sound procedure, if any, passing it the sound
  14237. number specified in the alert template for this stage of the alert. If no alert box
  14238. is to be drawn at this stage, Alert returns a function result of –1; otherwise, it
  14239. creates and displays the alert window for this alert and draws the alert box.
  14240.  
  14241. Warning:  If the alert template resource can’t be read, the function result
  14242.           is undefined.
  14243.  
  14244. Note:  Alert creates the alert window by calling NewDialog, and does the
  14245.        rest of its processing by calling ModalDialog.
  14246.  
  14247. Alert repeatedly gets and handles events in the alert window until an enabled item is
  14248. clicked, at which time it returns the item number. Normally you’ll then do whatever
  14249. is appropriate in response to a click of that item.
  14250.  
  14251. Alert gets each event by calling the Toolbox Event Manager function GetNextEvent. If
  14252. the event is a mouse-down event outside the content region of the alert window, Alert
  14253. emits sound number 1 (which should be a single beep) and gets the next event; otherwise,
  14254. it filters and handles the event as described below.
  14255.  
  14256. The filterProc parameter has the same meaning as in ModalDialog (see above). If it’s
  14257. NIL, the standard filterProc function is executed, which makes the Return key or the
  14258. Enter key have the same effect as clicking the default button. If you specify your
  14259. own filterProc function and want to retain this feature, you must include it in your
  14260. function. You can find out what the current default button is by looking at the
  14261. aDefItem field of the dialog record for the alert
  14262. (via the dialog pointer passed to the function).
  14263.  
  14264. Alert handles the events for which the filterProc function returns FALSE as follows:
  14265.  
  14266.   •  If the mouse button is pressed in a control, Alert calls the Control
  14267.      Manager procedure TrackControl. If the mouse button is released inside
  14268.      the control and the control is enabled, Alert returns; otherwise, it
  14269.      does nothing.
  14270.   •  If the mouse button is pressed in any other enabled item, Alert simply
  14271.      returns. If it’s pressed in any other disabled item or in no item, or
  14272.      if any other event occurs, Alert does nothing.
  14273.  
  14274. Before returning to the application with the item number, Alert removes the alert box
  14275. from the screen. (It disposes of the alert window and its associated data structures,
  14276. the item list, and the items.)
  14277.  
  14278. Note:  When an alert is removed, if it was overlapping the default button
  14279.        of a previous alert, that button’s bold outline won’t be redrawn.
  14280.  
  14281. Note:  The Alert function’s removal of the alert box would not be the
  14282.        desired result if the user clicked a check box or radio button;
  14283.        however, normally alerts contain only static text, icons, pictures,
  14284.        and buttons that are supposed to make the alert box go away. If your
  14285.        alert contains other items besides these, consider whether it might
  14286.        be more appropriate as a dialog.
  14287.  
  14288. The Alert function looks for a resource of type 'actb' with the same ID as the alert.
  14289. The alert color table is copied before it is passed to SetWinSize unless its ctSize
  14290. field is equal to –1, indicating that the default window colors are to be used instead.
  14291. The copy is made so that the color table resource can be purged without affecting the
  14292. alert.
  14293.  
  14294. The color dialog item list resource is duplicated as well, so it can be purgeable.
  14295.  
  14296. æKY StopAlert
  14297. æFc Dialogs.h
  14298. æT Function
  14299. æTN A986
  14300. æD pascal short StopAlert(short alertID,ModalFilterProcPtr filterProc)
  14301.     = 0xA986; 
  14302. æDT short myVariable = StopAlert((short) alertID,(ModalFilterProcPtr) filterProc);
  14303. æMM
  14304. æRI I-419, V-284, P-109, 182
  14305. æC  
  14306. StopAlert is the same as the Alert function (above) except that before drawing the
  14307. items of the alert in the alert box, it draws the Stop icon in the top left corner of
  14308. the box (within the rectangle (10,20)(42,52)). The Stop icon has the following resource
  14309. ID:
  14310.  
  14311. CONST stopIcon = 0;
  14312.  
  14313. If the application’s resource file doesn’t include an icon with that ID number, the
  14314. Dialog Manager uses the standard Stop icon in the system resource file (see Figure
  14315. 11).
  14316.  
  14317. The calls CautionAlert, StopAlert, and NoteAlert look for a resource of type
  14318. 'actb' with the same ID as the alert.
  14319.  
  14320. •••Refer to Figure 11.•••
  14321.  
  14322. Figure 11–Standard Alert Icons
  14323.  
  14324. æKY NoteAlert
  14325. æFc Dialogs.h
  14326. æT Function
  14327. æTN A987
  14328. æD pascal short NoteAlert(short alertID,ModalFilterProcPtr filterProc)
  14329.     = 0xA987; 
  14330. æDT short myVariable = NoteAlert((short) alertID,(ModalFilterProcPtr) filterProc);
  14331. æMM
  14332. æRI I-420
  14333. æC  
  14334. NoteAlert is like StopAlert except that it draws the Note icon, which has the following
  14335. resource ID:
  14336.  
  14337. CONST noteIcon = 1;
  14338.  
  14339. The calls CautionAlert, StopAlert, and NoteAlert look for a resource of type
  14340. 'actb' with the same ID as the alert.
  14341.  
  14342. æKY CautionAlert
  14343. æFc Dialogs.h
  14344. æT Function
  14345. æTN A988
  14346. æD pascal short CautionAlert(short alertID,ModalFilterProcPtr filterProc)
  14347.     = 0xA988; 
  14348. æDT short myVariable = CautionAlert((short) alertID,(ModalFilterProcPtr) filterProc);
  14349. æMM
  14350. æRI I-420
  14351. æC  
  14352. CautionAlert is like StopAlert except that it draws the Caution icon, which has the
  14353. following resource ID:
  14354.  
  14355. CONST cautionIcon = 2;
  14356.  
  14357. The calls CautionAlert, StopAlert, and NoteAlert look for a resource of type
  14358. 'actb' with the same ID as the alert.
  14359.  
  14360. æKY CouldAlert
  14361. æFc Dialogs.h
  14362. æT Function
  14363. æTN A989
  14364. æD pascal void CouldAlert(short alertID)
  14365.     = 0xA989; 
  14366. æDT CouldAlert((short) alertID);
  14367. æMM
  14368. æRI I-420, V-285
  14369. æC 
  14370. CouldAlert makes the alert template having the given resource ID unpurgeable
  14371. (reading it into memory if it’s not already there). It does the same for the alert
  14372. window’s definition function, the alert’s item list resource, and any items defined
  14373. as resources. This is useful if the alert may occur when the resource file isn’t
  14374. accessible, such as during a disk copy.
  14375.  
  14376. Warning:  Like CouldDialog, CouldAlert assumes your alerts use the system
  14377.           font; if you’ve changed the font with SetDAFont, calling CouldAlert
  14378.           doesn’t make the font unpurgeable.
  14379.  
  14380. The CouldAlert routine makes the alert color table template unpurgeable
  14381. (reading it into memory if it isn’t already there), if it exists. It does the same
  14382. for the alert’s color item list, if it has one.
  14383.  
  14384. Warning:  Like CouldDialog, CouldAlert doesn’t load or make 'FONT' or
  14385.           'FOND' resources indicated in the color item list unpurgeable.
  14386.  
  14387. æKY FreeAlert
  14388. æFc Dialogs.h
  14389. æT Function
  14390. æTN A98A
  14391. æD pascal void FreeAlert(short alertID)
  14392.     = 0xA98A; 
  14393. æDT FreeAlert((short) alertID);
  14394. æMM
  14395. æRI I-420, V-285
  14396. æC 
  14397. Given the resource ID of an alert template previously specified in a call to CouldAlert,
  14398. FreeAlert undoes the effect of CouldAlert (by making the resources purgeable). It
  14399. should be called when there’s no longer a need to keep the resources in memory.
  14400.  
  14401. Given the resource ID of an alert template previously specified in a call to CouldAlert,
  14402. the FreeAlert routine undoes the effect of CouldAlert, by restoring the original
  14403. purge state of the color table and color item list resources.
  14404.  
  14405. æKY GetDItem
  14406. æFc Dialogs.h
  14407. æT Function
  14408. æTN A98D
  14409. æD pascal void GetDItem(DialogPtr theDialog,short itemNo,short *itemType,Handle *item,
  14410.     Rect *box)
  14411.     = 0xA98D; 
  14412. æDT GetDItem((DialogPtr) theDialog,(short) itemNo,(short *) itemType,(Handle *) item,(
  14413.     Rect) * box);
  14414. æMM
  14415. æRI I-421
  14416. æC  
  14417. GetDItem returns in its VAR parameters the following information about the item
  14418. numbered itemNo in the given dialog’s item list:  In the itemType parameter, the item
  14419. type; in the item parameter, a handle to the item (or, for item type userItem, the
  14420. procedure pointer); and in the box parameter, the display rectangle for the item.
  14421.  
  14422. Suppose, for example, that you want to change the title of a control in a dialog box.
  14423. You can get the item handle with GetDItem, coerce it to type ControlHandle, and call
  14424. the Control Manager procedure SetCTitle to change the title. Similarly, to move the
  14425. control or change its size, you would call MoveControl or SizeControl.
  14426.  
  14427. Note:  To access the text of a statText or editText item, you can pass the
  14428.        handle returned by GetDItem to GetIText or SetIText (see below).
  14429.  
  14430. æKY SetDItem
  14431. æFc Dialogs.h
  14432. æT Function
  14433. æTN A98E
  14434. æD pascal void SetDItem(DialogPtr theDialog,short itemNo,short itemType,Handle item,
  14435.     const Rect *box)
  14436.     = 0xA98E; 
  14437. æDT SetDItem((DialogPtr) theDialog,(short) itemNo,(short) itemType,(Handle) item,(
  14438.     const Rect) * box);
  14439. æMM
  14440. æRT 34
  14441. æRI I-421, N34-1
  14442. æC  
  14443. SetDItem sets the item numbered itemNo in the given dialog’s item list, as specified
  14444. by the parameters (without drawing the item). The itemType parameter is the item
  14445. type; the item parameter is a handle to the item (or, for item type userItem, the
  14446. procedure pointer); and the box parameter is the display rectangle for the item.
  14447.  
  14448. Consider, for example, how to install an item of type userItem in a dialog:  In the
  14449. item list in the resource file, define an item in which the type is set to userItem
  14450. and the display rectangle to (0,0)(0,0). Specify that the dialog window be invisible
  14451. (in either the dialog template or the NewDialog call). After creating the dialog,
  14452. coerce the item’s procedure pointer to type Handle; then call SetDItem, passing that
  14453. handle and the display rectangle for the item. Finally, call the Window Manager
  14454. procedure ShowWindow to display the dialog window.
  14455.  
  14456. Note:  Do not use SetDItem to change the text of a statText or editText item
  14457.        or to change or move a control. See the description of GetDItem above
  14458.        for more information.
  14459.  
  14460. æKY HideDItem
  14461. æFc Dialogs.h
  14462. æT Function
  14463. æTN A827
  14464. æD pascal void HideDItem(DialogPtr theDialog,short itemNo)
  14465.     = 0xA827; 
  14466. æDT HideDItem((DialogPtr) theDialog,(short) itemNo);
  14467. æMM
  14468. æRI IV-59
  14469. æC 
  14470. HideDItem hides the item numbered itemNo in the given dialog’s item list by giving
  14471. the item a display rectangle that’s off the screen. (Specifically, if the left coordinate
  14472. of the item’s display rectangle is less than 8192, ShowDItem adds 16384 to both the
  14473. left and right coordinates the rectangle.) If the item is already hidden (that is, if
  14474. the left coordinate is greater than 8192), HideDItem does nothing.
  14475.  
  14476. HideDItem calls the EraseRect procedure on the item’s enclosing rectangle and adds
  14477. the rectangle that contained the item (not necessarily the item’s display rectangle)
  14478. to the update region. If the specified item is an active editText item, the item is
  14479. first deactivated (by calling TEDeactivate).
  14480.  
  14481. Note:  If you have items that are close to each other, be aware that the
  14482.        Dialog Manager draws outside of the enclosing rectangle by 3 pixels
  14483.        for editText items and by 4 pixels for a default button.
  14484.  
  14485. An item that’s been hidden by HideDItem can be redisplayed by the ShowDItem procedure.
  14486.  
  14487. Note:  To create a hidden item in a dialog item list, simply add 16384 to
  14488.        the left and right coordinates of the display rectangle.
  14489.  
  14490. æKY ShowDItem
  14491. æFc Dialogs.h
  14492. æT Function
  14493. æTN A828
  14494. æD pascal void ShowDItem(DialogPtr theDialog,short itemNo)
  14495.     = 0xA828; 
  14496. æDT ShowDItem((DialogPtr) theDialog,(short) itemNo);
  14497. æMM
  14498. æRI IV-59
  14499. æC 
  14500. ShowDItem redisplays the item numbered itemNo, previously hidden by HideDItem, by
  14501. giving the item the display rectangle it had prior to the HideDItem call.
  14502. (Specifically, if the left coordinate of the item’s display rectangle is greater than
  14503. 8192, ShowDItem subtracts 16384 from both the left and right coordinates of the rectangle.)
  14504. If the item is already visible (that is, if the left coordinate is less than 8192),
  14505. ShowDItem does nothing.
  14506.  
  14507. ShowDItem adds the rectangle that contained the item (not necessarily the
  14508. item’s display rectangle) to the update region so that it will be drawn. If the item
  14509. becomes the only editText item, ShowDItem activates it (by calling TEActivate).
  14510.  
  14511. æKY SelIText
  14512. æFc Dialogs.h
  14513. æT Function
  14514. æTN A97E
  14515. æD pascal void SelIText(DialogPtr theDialog,short itemNo,short strtSel,short endSel)
  14516.     = 0xA97E; 
  14517. æDT SelIText((DialogPtr) theDialog,(short) itemNo,(short) strtSel,(short) endSel);
  14518. æMM
  14519. æRI I-422, P-110
  14520. æC 
  14521. Given a pointer to a dialog and the item number of an editText item in the dialog
  14522. box, SelIText does the following:
  14523.  
  14524.   •  If the item contains text, SelIText sets the selection range to extend
  14525.      from character position strtSel up to but not including character
  14526.      position endSel. The selection range is inverted unless strtSel equals
  14527.      endSel, in which case a blinking vertical bar is displayed to indicate
  14528.      an insertion point at that position.
  14529.   •  If the item doesn’t contain text, SelIText simply displays the insertion
  14530.      point.
  14531.  
  14532. For example, if the user makes an unacceptable entry in the editText item, the application
  14533. can put up an alert box reporting the problem and then select the entire text of the
  14534. item so it can be replaced by a new entry. (Without this procedure, the user would
  14535. have to select the item before making the new entry.)
  14536.  
  14537. Note:  You can select the entire texxt by specifying 0 for strtSel and 32767
  14538.        for endSel. For details about selection range and character position,
  14539.        see the TextEdit chapter.
  14540.  
  14541. æKY GetIText
  14542. æFc Dialogs.h
  14543. æT Function
  14544. æTN A990
  14545. æD pascal void GetIText(Handle item,Str255 text)
  14546.     = 0xA990; 
  14547. æDT GetIText((Handle) item,(Str255) text);
  14548. æRT 18
  14549. æRI I-422, N18-2
  14550. æC  
  14551. Given a handle to a statText or editText item in a dialog box, as returned by GetDItem,
  14552. GetIText returns the text of the item in the text parameter. (If the user typed more
  14553. than 255 characters in an editText item, GetIText returns only the first 255.)
  14554.  
  14555. æKY SetIText
  14556. æFc Dialogs.h
  14557. æT Function
  14558. æTN A98F
  14559. æD pascal void SetIText(Handle item,const Str255 text)
  14560.     = 0xA98F; 
  14561. æDT SetIText((Handle) item,(const Str255) text);
  14562. æMM
  14563. æRI I-422
  14564. æC 
  14565. Given a handle to a statText or editText item in a dialog box, as returned by GetDItem,
  14566. SetIText sets the text of the item to the specified text and draws the item. For
  14567. example, suppose the exact content of a dialog’s text item cannot be determined until
  14568. the application is running, but the display rectangle is defined in the resource
  14569. file:  Call GetDItem to get a handle to the item, and call SetIText with the desired
  14570. text.
  14571.  
  14572. æKY FindDItem
  14573. æFc Dialogs.h
  14574. æT Function
  14575. æTN A984
  14576. æD pascal short FindDItem(DialogPtr theDialog,Point thePt)
  14577.     = 0xA984; 
  14578. æDT short myVariable = FindDItem((DialogPtr) theDialog,(Point) thePt);
  14579. æMM
  14580. æRT 112
  14581. æRI IV-60, N112
  14582. æC 
  14583. FindDItem returns the item number of the item containing the point specified, in
  14584. local coordinates, by thePt. If the point doesn’t lie within the item’s rectangle,
  14585. FindDItem returns –1. If there are overlapping items, it returns the item number of
  14586. the first item in the list containing the point. FindDItem is useful for changing the
  14587. cursor when it’s over a particular item.
  14588.  
  14589. Note:  FindDItem will return the item number of disabled items as well.
  14590.  
  14591. æKY NewCDialog
  14592. æFc Dialogs.h
  14593. æT Function
  14594. æTN AA4B
  14595. æD pascal DialogPtr NewCDialog(Ptr dStorage,const Rect *boundsRect,const Str255 title,
  14596.     Boolean visible,short procID,WindowPtr behind,Boolean goAwayFlag,long refCon,
  14597.     Handle items)
  14598.     = 0xAA4B; 
  14599. æDT DialogPtr myVariable = NewCDialog((Ptr) dStorage,(const Rect *) boundsRect,(const Str255) title,()
  14600.     Boolean visible,(short) procID,(WindowPtr) behind,(Boolean) goAwayFlag,(long) refCon,()
  14601.     Handle items);
  14602. æMM
  14603. æRI V-283
  14604. æC 
  14605. A new Dialog Manager routine has been added to support color dialogs: NewCDialog. 
  14606. Its parameters are identical to NewDialog, except that a cGrafPort is allocated
  14607. through a NewCWindow call instead of a call to NewWindow.
  14608.  
  14609. NewCDialog creates a dialog box as specified by its parameters and returns a cDialogPtr
  14610. to the new dialog. The first eight parameters (dStorage through refCon) are passed to
  14611. the Window Manager function NewCWindow, which creates the dialog window. The items
  14612. parameter is a handle to the dialog’s item list. You can get the items handle by
  14613. calling the Resource Manager to read the item list from the resource file into memory.
  14614.  
  14615. After calling NewCDialog, you can use SetWinColor to add a color table to the dialog.
  14616. This creates an auxiliary window record (auxWinRec) for the dialog window. You can
  14617. access this record with the GetAuxWin routine. The dialogCItem handle within the
  14618. auxWinRec points to the dialog item color table.
  14619.  
  14620. If the dialog’s content color isn’t white, it’s a good idea to call NewCDialog with
  14621. the visible flag set to FALSE. After the color table and color item list are installed,
  14622. use ShowWindow to display the dialog if the dialog is the frontmost window. If the
  14623. dialog is not in front, use ShowHide to display the dialog.
  14624.  
  14625. æKY newcdialog
  14626. æFc Dialogs.h
  14627. æT Function
  14628. æD DialogPtr newcdialog(Ptr dStorage,const Rect *boundsRect,char *title,Boolean visible,
  14629.     short procID,WindowPtr behind,Boolean goAwayFlag,long refCon,Handle items); 
  14630. æDT DialogPtr myVariable = newcdialog((Ptr) dStorage,(const Rect *) boundsRect,(char *) title,(Boolean) visible,()
  14631.     short procID,(WindowPtr) behind,(Boolean) goAwayFlag,(long) refCon,(Handle) items);
  14632. æRI V-283
  14633. æC 
  14634. A new Dialog Manager routine has been added to support color dialogs: NewCDialog. 
  14635. Its parameters are identical to NewDialog, except that a cGrafPort is allocated
  14636. through a NewCWindow call instead of a call to NewWindow.
  14637.  
  14638. NewCDialog creates a dialog box as specified by its parameters and returns a cDialogPtr
  14639. to the new dialog. The first eight parameters (dStorage through refCon) are passed to
  14640. the Window Manager function NewCWindow, which creates the dialog window. The items
  14641. parameter is a handle to the dialog’s item list. You can get the items handle by
  14642. calling the Resource Manager to read the item list from the resource file into memory.
  14643.  
  14644. After calling NewCDialog, you can use SetWinColor to add a color table to the dialog.
  14645. This creates an auxiliary window record (auxWinRec) for the dialog window. You can
  14646. access this record with the GetAuxWin routine. The dialogCItem handle within the
  14647. auxWinRec points to the dialog item color table.
  14648.  
  14649. If the dialog’s content color isn’t white, it’s a good idea to call NewCDialog with
  14650. the visible flag set to FALSE. After the color table and color item list are installed,
  14651. use ShowWindow to display the dialog if the dialog is the frontmost window. If the
  14652. dialog is not in front, use ShowHide to display the dialog.
  14653.  
  14654. æKY GetAlrtStage
  14655. æFc Dialogs.h
  14656. æT Function
  14657. æD pascal short GetAlrtStage(void)
  14658.     = {0x3EB8,0x0A9A}; 
  14659. æDT short myVariable = GetAlrtStage()(void);
  14660. æRI I-422
  14661. æC  
  14662. GetAlrtStage returns the stage of the last occurrence of an alert, as a number from 0
  14663. to 3.
  14664.  
  14665. Assembly-language note:  Assembly-language programmers can get this number
  14666.                          by accessing the global variable ACount. In addition,
  14667.                          the global variable ANumber contains the resource ID
  14668.                          of the alert template of the last alert that occurred.
  14669.  
  14670. æKY ResetAlrtStage
  14671. æFc Dialogs.h
  14672. æT Function
  14673. æD pascal void ResetAlrtStage(void)
  14674.     = {0x4278,0x0A9A}; 
  14675. æDT ResetAlrtStage()(void);
  14676. æRI I-423
  14677. æC 
  14678. ResetAlrtStage resets the stage of the last occurrence of an alert so that the next
  14679. occurrence of that same alert will be treated as its first stage. This is useful, for
  14680. example, when you’ve used ParamText to change the text of an alert such that from the
  14681. user’s point of view it’s a different alert.
  14682.  
  14683. Assembly-language note:  Assembly-language programmers can set the global
  14684.                          variable ACount to –1 for the same effect.
  14685.  
  14686. æKY DlgCut
  14687. æFc Dialogs.h
  14688. æT Function
  14689. æD pascal void DlgCut(DialogPtr theDialog); 
  14690. æDT DlgCut((DialogPtr) theDialog);
  14691. æRT 215
  14692. æRI I-418, P-110
  14693. æC 
  14694. [Not in ROM]
  14695. DlgCut checks whether theDialog has any editText items and, if so, applies the TextEdit
  14696. procedure TECut to the currently selected editText item. (If the dialog record’s
  14697. editField is 0 or greater, DlgCut passes the contents of the textH field to TECut.)
  14698. You can call DlgCut to handle the editing command Cut when a modeless dialog window
  14699. is active.
  14700.  
  14701. Assembly-language note:  Assembly-language programmers can just read the
  14702.                          dialog record’s fields and call TextEdit directly.
  14703.  
  14704. æKY DlgPaste
  14705. æFc Dialogs.h
  14706. æT Function
  14707. æD pascal void DlgPaste(DialogPtr theDialog); 
  14708. æDT DlgPaste((DialogPtr) theDialog);
  14709. æMM
  14710. æRT 215
  14711. æRI I-418, P-110
  14712. æC  
  14713. [Not in ROM]
  14714.  
  14715. DlgPaste is the same as DlgCut (above) except that it calls TEPaste, for handling the
  14716. Paste command.
  14717.  
  14718. æKY DlgCopy
  14719. æFc Dialogs.h
  14720. æT Function
  14721. æD pascal void DlgCopy(DialogPtr theDialog); 
  14722. æDT DlgCopy((DialogPtr) theDialog);
  14723. æMM
  14724. æRT 215
  14725. æRI I-418, P-110
  14726. æC 
  14727. [Not in ROM]
  14728. DlgCopy is the same as DlgCut (above) except that it calls TECopy, for handling the
  14729. Copy command.
  14730.  
  14731. æKY DlgDelete
  14732. æFc Dialogs.h
  14733. æT Function
  14734. æD pascal void DlgDelete(DialogPtr theDialog); 
  14735. æDT DlgDelete((DialogPtr) theDialog);
  14736. æMM
  14737. æRT 215
  14738. æRI I-418, P-110
  14739. æC  
  14740. [Not in ROM]
  14741.  
  14742. DlgDelete is the same as DlgCut (above) except that it calls TEDelete, for handling
  14743. the Clear command.
  14744.  
  14745. æKY SetDAFont
  14746. æFc Dialogs.h
  14747. æT Function
  14748. æD pascal void SetDAFont(short fontNum); 
  14749. æDT SetDAFont((short) fontNum);
  14750. æRI I-412
  14751. æC 
  14752. For subsequently created dialogs and alerts, SetDAFont causes the font of the dialog
  14753. or alert window’s grafPort to be set to the font having the specified font number. If
  14754. you don’t call this procedure, the system font is used. SetDAFont affects statText
  14755. and editText items but not titles of controls, which are always in the system font.
  14756.  
  14757. Assembly-language note:  Assembly-language programmers can simply set
  14758.                          the global variable DlgFont to the desired font number.
  14759.  
  14760. æKY paramtext
  14761. æFc Dialogs.h
  14762. æT Function
  14763. æD void paramtext(char *param0,char *param1,char *param2,char *param3); 
  14764. æDT paramtext((char *) param0,(char *) param1,(char *) param2,(char *) param3);
  14765. æMM
  14766. æRI I-421
  14767. æC  
  14768. ParamText provides a means of substituting text in statText items:  param0 through
  14769. param3 will replace the special strings '^0' through '^3' in all statText items in
  14770. all subsequent dialog or alert boxes. Pass empty strings for parameters not used.
  14771.  
  14772. Assembly-language note:  Assembly-language programmers may pass NIL for
  14773.                          parameters not used or for strings that are not
  14774.                          to be changed.
  14775.  
  14776. For example, if the text is defined as 'Cannot open document ^0' and docName is a
  14777. string variable containing a document name that the user typed, you can call ParamText(docName,'
  14778. ',' ',' ')
  14779.  
  14780. Note:  All strings that may need to be translated to other languages should
  14781.        be stored in resource files.
  14782.  
  14783. Assembly-language note:  The Dialog Manager stores handles to the four
  14784.                          ParamText parameters in a global array named DAStrings.
  14785.  
  14786. æKY getitext
  14787. æFc Dialogs.h
  14788. æT Function
  14789. æD void getitext(Handle item,char *text); 
  14790. æDT getitext((Handle) item,(char *) text);
  14791. æRT 18
  14792. æRI I-422, N18-2
  14793. æC  
  14794. Given a handle to a statText or editText item in a dialog box, as returned by GetDItem,
  14795. GetIText returns the text of the item in the text parameter. (If the user typed more
  14796. than 255 characters in an editText item, GetIText returns only the first 255.)
  14797.  
  14798. æKY setitext
  14799. æFc Dialogs.h
  14800. æT Function
  14801. æD void setitext(Handle item,char *text); 
  14802. æDT setitext((Handle) item,(char *) text);
  14803. æMM
  14804. æRI I-422
  14805. æC 
  14806. Given a handle to a statText or editText item in a dialog box, as returned by GetDItem,
  14807. SetIText sets the text of the item to the specified text and draws the item. For
  14808. example, suppose the exact content of a dialog’s text item cannot be determined until
  14809. the application is running, but the display rectangle is defined in the resource
  14810. file:  Call GetDItem to get a handle to the item, and call SetIText with the desired
  14811. text.
  14812.  
  14813. æKY findditem
  14814. æFc Dialogs.h
  14815. æT Function
  14816. æD short findditem(DialogPtr theDialog,Point *thePt); 
  14817. æDT short myVariable = findditem((DialogPtr) theDialog,(Point *) thePt);
  14818. æRI IV-60, N112
  14819. æC 
  14820. FindDItem returns the item number of the item containing the point specified, in
  14821. local coordinates, by thePt. If the point doesn’t lie within the item’s rectangle,
  14822. FindDItem returns –1. If there are overlapping items, it returns the item number of
  14823. the first item in the list containing the point. FindDItem is useful for changing the
  14824. cursor when it’s over a particular item.
  14825.  
  14826. Note:  FindDItem will return the item number of disabled items as well.
  14827.  
  14828.  
  14829. æKY DisAsmLookup.h
  14830. æKL Disassembler
  14831. endOfModule
  14832. InitLookup
  14833. Lookup
  14834. LookupTrapName
  14835. ModifyOperand
  14836. showMacsBugSymbol
  14837. validMacsBugSymbol
  14838.  
  14839. _A0_
  14840. _A1_
  14841. _A2_
  14842. _A3_
  14843. _A4_
  14844. _A5_
  14845. _A6_
  14846. _A7_
  14847. _ABS_
  14848. _PC_
  14849. _TRAP_
  14850. LookupRegs
  14851.  
  14852. æKY Disassembler
  14853. æFc DisAsmLookup.h
  14854. æT Function
  14855. æD pascal void Disassembler(long DstAdjust,short *BytesUsed,Ptr FirstByte,
  14856.     char *Opcode,char *Operand,char *Comment,Ptr LookUpProc);
  14857. æDT Disassembler((long)DstAdjust,(short *)BytesUsed,(Ptr)FirstByte,
  14858.     (char *)Opcode,(char *)Operand,(char *)Comment,(Ptr)LookUpProc);
  14859. æC 
  14860. /* 
  14861.     Disassembler is a Pascal routine to be called to disassemble a sequence of
  14862.     bytes.  All MC68xxx, MC68881, and MC68851 instructions are supported.  The
  14863.     sequence of bytes to be disassembled are pointed to by FirstByte.  BytesUsed
  14864.     bytes starting at FirstByte are consumed by the disassembly, and the Opcode,
  14865.     Operand, and Comment strings returned as NULL TERMINATED Pascal strings (for
  14866.     easier manipulation with C).  The caller is then free to format or use the
  14867.     output strings any way appropriate to the application.
  14868.     
  14869.     Depending on the opcode and effective address(s) (EA's) to be disassembled,
  14870.     the Opcode, Operand, and Comment strings contain the following information:
  14871.     
  14872.     Case                     Opcode    Operand    Comment
  14873.     =======================================================================
  14874.     Non PC-relative EA's     op.sz     EA's
  14875.     PC-relative EA's         op.sz     EA's       ; address
  14876.     Toolbox traps            DC.W      $AXXX      ; TB XXXX
  14877.     OS traps                 DC.W      $AXXX      ; OS XXXX
  14878.     Invalid bytes            DC.W      $XXXX      ; ????
  14879.     Invalid byte #immediate  DC.W      $XXXX,...  ; op.sz #$??XX,EA
  14880.     =======================================================================
  14881.     
  14882.     For valid disassembly of processor instructions the appropriate MC68XXX
  14883.     opcode mnemonic is generated for the Opcode string along with a size
  14884.     attribute when required. The source and destination EA's are generated as the
  14885.     Operand along with a possible comment.  Comments start with a ';'.  Traps use
  14886.     a DC.W assembler directive as the Opcode with the trap word as the Operand
  14887.     and a comment indicating whether the trap is a toolbox or OS trap and what
  14888.     the trap number is.  As described later the caller can generate symbolic
  14889.     substitutions into EA's and provide names for traps.
  14890.     
  14891.     Invalid instructions cause the string 'DC.W' to be returned in the Opcode
  14892.     string. Operand is '$XXXX' (the invalid word) with a comment of '; ????'.
  14893.     BytesUsed is 2. This is similar to the trap call case except for the comment.
  14894.     
  14895.     A special case is made for immediate byte operands with a nonzero high order
  14896.     byte.  For example, the bytes $020011FF, when actually executed, would be
  14897.     interpreted as ANDI.B $FF,D0. The processor will IGNORE the high order byte
  14898.     of the immediate data! Thus, the bytes may be considered as valid.  Since the
  14899.     Disassembler has no way of knowing the context in which it is disassembling,
  14900.     it returns the Opcode as 'DC.W' as in the normal invalid case.  However, the
  14901.     Operand string shows ALL the words disassembled separated with commas and
  14902.     places the possibly valid disassembly in the Operand's comment indicating the
  14903.     nonzero bytes. Thus for the example $020011FF bytes, the Opcode will be
  14904.     'DC.W', the Operand will be '$0200,$11FF', and the Comment 
  14905.     '; ANDI.B #$??FF,D0'.  BytesUsed in this case would be 4.
  14906.     
  14907.     Note, the Operand EA's is syntatically similar to but NOT COMPATIBLE with the
  14908.     MPW assembler!  This is because the Disassembler generates byte hex constants
  14909.     as "$XX" and word hex constants as "$XXXX".  Negative values (e.g., $FF or
  14910.     $FFFF) produced by the Disassembler are treated as long word values by the MPW
  14911.     assembler.  Thus it is assumed that Disassembler output will NOT be used as
  14912.     MPW assembler input. If that is the goal, then the caller must convert strings
  14913.     of the form $XX or $XXXX in the Operand string to their decimal equivalent.
  14914.     The routine ModifyOperand is provided in this unit to aid with the conversion
  14915.     process.
  14916.     
  14917.     Since a PC-relative comment is an address, the only address that the
  14918.     Disassembler knows about is the address of the code pointed to by FirstByte.
  14919.     Generally, that may be a buffer that has no relation to "reality", i.e., the
  14920.     actual code loaded into the buffer.  Therefore, to allow the address comment
  14921.     to be mapped back to some actual address the caller may specify an adjustment
  14922.     factor, specified by DstAdjust that is ADDED to the value that normally would
  14923.     be placed in the comment.
  14924.     
  14925.     Operand effective address strings are generated as a function of the 
  14926.     effective address mode and a special case is made for A-trap opcode strings.
  14927.     In places where a possible symbolic reference could be substituted for an
  14928.     address (or a portion of an address), the Disassembler can call a user
  14929.     specified routine to do the substitution (using th LookupProc parameter
  14930.     described later).  The following table summarizes the generated effective
  14931.     addresses and where symbolic substitutions (S) can be made:
  14932.          
  14933.     Mode    Generated Effective Address  Effective Address with Substitution
  14934.     ========================================================================
  14935.       0     Dn                           Dn
  14936.       1     An                           An
  14937.       2     (An)                         (An)
  14938.       3     (An)+                        (An)+
  14939.       4     -(An)                        -(An)
  14940.       5     ∂(An)                        S(An) or just S (if An=A5, ∂≥0)
  14941.      6n     ∂(An,Xn.Size*Scale)          S(An,Xn.Size*Scale)
  14942.      6n     (BD,An,Xn.Size*Scale)        (S,An,Xn.Size*Scale)
  14943.      6n     ([BD,An],Xm.Size*Scale,OD)   ([S,An],Xm.Size*Scale,OD)
  14944.      6n     ([BD,An,Xn.Size*Scale],OD)   ([S,An,Xn.Size*Scale],OD)
  14945.      70     ∂                            S
  14946.      71     ∂                            S
  14947.      72     *±∂                          S
  14948.      73     *±∂(Xn.Size*Scale)           S(Xn.Size*Scale)
  14949.      73     (*±∂,Xn.Size*Scale)          (S,Xn.Size*Scale)
  14950.      73     ([*±∂],Xm.Size*Scale,OD)     ([S],Xm.Size*Scale,OD)
  14951.      73     ([*±∂,Xn.Size*Scale],OD)     ([S,Xn.Size*Scale],OD)
  14952.      74     #data                        #data
  14953.     ========================================================================
  14954.     
  14955.     For A-traps, the substitution can be performed to substitute for the DC.W
  14956.     opcode string.  If the substitution is made then the Disassembler will
  14957.     generate ,Sys and/or ,Immed flags as operands for Toolbox traps and
  14958.     ,AutoPop for OS traps when the bits in the trap word indicates these
  14959.     settings.
  14960.     
  14961.             |         Generated          |            Substituted
  14962.             | Opcode  Operand  Comment   | Opcode  Operand        Comment
  14963.     ========================================================================
  14964.     Toolbox | DC.W    $AXXX    ; TB XXXX | S       [,Sys][,Immed] ; AXXX
  14965.     OS      | DC.W    $AXXX    ; OS XXXX | S       [,AutoPop]     ; AXXX
  14966.     ========================================================================
  14967.     
  14968.     All displacements (∂, BD, OD) are hexadecimal values shown as a byte ($XX),
  14969.     word ($XXXX), or long ($XXXXXXXX) as appropriate. The *Scale is suppressed if
  14970.     1. The Size is W or L.  Note that effective address substitutions can only be
  14971.     made for "∂(An)", "BD,An", and "*±∂" cases.
  14972.         
  14973.     For all the effective address modes 5, 6n, 7n, and for A-traps, a coroutine (a
  14974.     procedure) whose address is specified by the LookupProc parameter is called by
  14975.     the Disassembler (if LookupProc is not NIL) to do the substitution (or A-trap
  14976.     comment) with a string returned by the proc.  It is assumed that the proc
  14977.     pointed to by LookupProc is a level 1 Pascal proc declared as follows:
  14978.     
  14979.     PROCEDURE Lookup(     PC:      UNIV Ptr;     {Addr of extension/trap word}
  14980.                          BaseReg: LookupRegs;   {Base register/lookup mode  }
  14981.                          Opnd:    UNIV LongInt; {Trap word, PC addr, disp.  }
  14982.                      VAR S:       DisAsmStr80); {Returned substitution      }
  14983.     
  14984.     where TYPE DisAsmStr80 = String[80];
  14985.       
  14986.     or in C,
  14987.     
  14988.     pascal void LookUp(Ptr         PC, 
  14989.                        LookupRegs  BaseReg, 
  14990.                        long        Opnd, 
  14991.                        char        *S); 
  14992.     
  14993.     PC      = Pointer to instruction extension word or A-trap word in the
  14994.               buffer pointed to by the Disassembler's FirstByte parameter.
  14995.               
  14996.     BaseReg = This determines the meaning of the Opnd value and supplies
  14997.               the base register for the "∂(An)", "BD,An", and "*±∂" cases.
  14998.               BaseReg may contain any one of the following values:
  14999.              
  15000.               _A0_   =  0 ==> A0
  15001.               _A1_   =  1 ==> A1
  15002.               _A2_   =  2 ==> A2
  15003.               _A3_   =  3 ==> A3
  15004.               _A4_   =  4 ==> A4
  15005.               _A5_   =  5 ==> A5
  15006.               _A6_   =  6 ==> A6
  15007.               _A7_   =  7 ==> A7
  15008.               _PC_   =  8 ==> PC-relative (special case)
  15009.               _ABS_  =  9 ==> Abs addr    (special case)
  15010.               _TRAP_ = 10 ==> Trap word   (special case)
  15011.               
  15012.               For absolute addressing (modes 70 and 71),  BaseReg contains _ABS_.
  15013.               For A-traps, BaseReg would contain _TRAP_.
  15014.     
  15015.     Opnd    = The contents of this LongInt is determined by the BaseReg parameter
  15016.               just described.
  15017.            
  15018.               For BaseReg = _TRAP_ (A-traps):
  15019.                   Opnd is the entire trap word. The high order 16 bits of Opnd are
  15020.                   zero.
  15021.     
  15022.               For BaseReg = _ABS_  (absolute effective address):
  15023.                   Opnd contains the (extended) 32-bit address specifed by the
  15024.                   instruction's effective address.  Such addresses would generally
  15025.                   be used to reference low memory globals on a Macintosh.
  15026.     
  15027.               For BaseReg = _PC_  (PC-relative effective address):
  15028.                   Opnd contains the 32-bit address represented by "*±∂" adjusted
  15029.                   by the Disassembler's DstAdjust parameter.
  15030.                   
  15031.               For BaseReg = _An_  (effective address with a base register):
  15032.                   Opnd contains the (sign-extended) 32-bit (base) displacement
  15033.                   from the instruction's effective address.
  15034.                   
  15035.                   In the Macintosh environment, a BaseReg specifying A5 implies
  15036.                   either global data references or Jump Table references. Positive
  15037.                   Opnd values with an A5 BaseReg thus mean Jump Table references,
  15038.                   while a negative offset would mean a global data reference.
  15039.                   Base registers of A6 or A7 would usually mean local data.
  15040.     
  15041.     S       = Pascal string returned from Lookup containing the effective address
  15042.               substitution string or a trap name for A-traps.  S is set to null
  15043.               PRIOR to calling Lookup.  If it is still null on return, the string
  15044.               is not used.  If not null, then for A-traps, the returned string is
  15045.               used as a opcode string. In all other cases the string is
  15046.               substituted as shown in the above table.
  15047.                
  15048.     Depending on the application, the caller has three choices on how to use the
  15049.     Disassembler and an associated Lookup proc:
  15050.     
  15051.     (1). The caller can call just the Disassembler and provide his own Lookup
  15052.          proc. In that case the calling conventions discussed above must be
  15053.          followed.
  15054.     
  15055.     (2). The caller can provide NIL for the LookupProc parameter, in which case,
  15056.          NO Lookup proc will be called.
  15057.          
  15058.     (3). The caller can call first InitLookup (described below, a proc provided
  15059.          with this unit) and pass the address of this unit's standard Lookup proc
  15060.          when Disassembler is called.  In this case all the control logic to
  15061.          determine the kind of substitution to be done is provided for the caller
  15062.          and all that need to be provided by the user are routines to look up any
  15063.          or all of the following:
  15064.          
  15065.          • PC-relative references
  15066.          • Jump Table references
  15067.          • Absolute address references
  15068.          • Trap names
  15069.          • References with offsets from base registers 
  15070. */
  15071.  
  15072. æKY endOfModule
  15073. æFc DisAsmLookup.h
  15074. æT Function
  15075. æD char *endOfModule(void *address,void *limit,char *symbol,void **nextModule);
  15076. æDT char myVariable = endOfModule((void *)address,(void *)limit,(char *)symbol,
  15077.     (void *)*nextModule);
  15078. æC 
  15079. /* 
  15080.     Check to see if the specified memory address, contains a RTS, JMP (A0) or
  15081.     RTD #n instruction immediately followed by a valid MacsBug symbol.  These
  15082.     sequences are the only ones which can determine an end of module when MacsBug
  15083.     symbols are present.  During the check, the instruction and its following
  15084.     MacsBug symbol must be fully contained in the bytes starting at the specified
  15085.     address parameter, up to, but not including, the byte pointed to by the limit
  15086.     parameter.
  15087.     
  15088.     If the end of module is NOT found, then NULL is returned as the function's
  15089.     result.  However, if a end of module is found, the MacsBug symbol is returned
  15090.     in symbol (if it is not NULL) as a null terminated Pascal string (with trailing
  15091.     blanks removed), and the functions returns the pointer to the start of the
  15092.     MacsBug symbol (i.e., address+2 for RTS or JMP (A0) and address+4 for RTD #n).
  15093.     This address may then be used as in input parameter to showMacsBugSymbol to
  15094.     convert the MacsBug symbol to a Disassembler operand string.
  15095.     
  15096.     Also returned in nextModule is where we think the FOLLOWING module begins. In
  15097.     the "old style" cases (see validMacsBugSymbol) this will always be 8 or 16
  15098.     bytes after the input address.  For new style the Apple Pascal and C cases this
  15099.     will depend on the symbol length, existence of a pad byte, and size of the
  15100.     constant (literal) area.  See validMacsBugSymbol for a description of valid
  15101.     MacsBug symbol formats. 
  15102. */
  15103.  
  15104. æKY InitLookup
  15105. æFc DisAsmLookup.h
  15106. æT Function
  15107. æD pascal void InitLookup(Ptr PCRelProc,Ptr JTOffProc,Ptr TrapProc,Ptr AbsAddrProc,
  15108.     Ptr IdProc);
  15109. æDT InitLookup((Ptr)PCRelProc,(Ptr)JTOffProc,(Ptr)TrapProc,
  15110.     (Ptr)AbsAddrProc,(Ptr)IdProc);
  15111. æC 
  15112. /* 
  15113.     Prepare for use of this unit's Lookup proc.  When Disassembler is called
  15114.     and the address of this unit's Lookup proc is specified, then for PC-relative,
  15115.     Jump Table references, A-traps, absolute addresses, and offsets from a base
  15116.     register, the associated level 1 Pascal proc specified here is called (if not
  15117.     NULL -- all five addresses are preset to NULL). The calls assume the following
  15118.     declarations for these procs (see Lookup, below for further details):
  15119.                                  
  15120.     PROCEDURE PCRelProc(Address: UNIV LongInt; 
  15121.                         VAR S:   UNIV DisAsmStr80);
  15122.     
  15123.     PROCEDURE JTOffProc(A5JTOffset: UNIV Integer;
  15124.                         VAR S:      UNIV DisAsmStr80);
  15125.     
  15126.     PROCEDURE TrapNameProc(TrapWord: UNIV Integer;
  15127.                            VAR S:     UNIV DisAsmStr80);
  15128.                             
  15129.     PROCEDURE AbsAddrProc(AbsAddr: UNIV LongInt;
  15130.                           VAR S:   UNIV DisAsmStr80);
  15131.     
  15132.     PROCEDURE IdProc(BaseReg: LookupRegs;
  15133.                      Offset:  UNIV LongInt;
  15134.                      VAR S:    UNIV DisAsmStr80);
  15135.     
  15136.     or in C,
  15137.     
  15138.     pascal void PCRelProc(long Address, char *S)
  15139.     
  15140.     pascal void JTOffProc(short A5JTOffset, char *S)
  15141.     
  15142.     pascal void TrapNameProc(unsigned short TrapWord, char *S)
  15143.     
  15144.     pascal void AbsAddrProc(long AbsAddr, char *S)
  15145.     
  15146.     pascal void IdProc(LookupRegs BaseReg, long Offset, char *S)
  15147.     
  15148.     Note: InitLookup contains initialized data which requires initializing at load
  15149.           time (this is of concern only to users with assembler main programs.
  15150. */
  15151.  
  15152. æKY Lookup
  15153. æFc DisAsmLookup.h
  15154. æT Function
  15155. æD pascal void Lookup(Ptr PC,LookupRegs BaseReg,long Opnd,char *S);
  15156. æDT Lookup((Ptr)PC,(LookupRegs)BaseReg,(long)Opnd,(char *)S);
  15157. æC 
  15158. /* 
  15159.     This is a standard Lookup proc available to the caller for calls to the
  15160.     Disassembler.  If the caller elects to use this proc, then InitLookup MUST be
  15161.     called prior to any calls to the Disassembler.  All the logic to determine the
  15162.     type of lookup is done by this proc.  For PC-relative, Jump Table references,
  15163.     A-traps, absolute addresses, and offsets from a base register, the associated
  15164.     level 1 Pascal proc specified in the InitLookup call (if not NULL) is called.
  15165.     
  15166.     This scheme simplifies the Lookup mechanism by allowing the caller to deal
  15167.     with just the problems related to the application.
  15168. */
  15169.  
  15170.  
  15171. æKY LookupRegs
  15172. _A0_
  15173. _A1_
  15174. _A2_
  15175. _A3_
  15176. _A4_
  15177. _A5_
  15178. _A6_
  15179. _A7_
  15180. _PC_
  15181. _ABS_
  15182. _TRAP_
  15183. æFc DisAsmLookup.h
  15184. æD enum {_A0_,_A1_,_A2_,_A3_,_A4_,_A5_,_A6_,_A7_,_PC_,_ABS_,_TRAP_}LookupRegs;
  15185. typedef unsigned char LookupRegs;
  15186.  
  15187.  
  15188. æKY LookupTrapName
  15189. æFc DisAsmLookup.h
  15190. æT Function
  15191. æD pascal void LookupTrapName(unsigned short TrapWord,char *S);
  15192. æDT LookupTrapName((unsigned short)TrapWord,(char *)S);
  15193. æC 
  15194. /* 
  15195.     This is a procedure provided to allow conversion of a trap instruction (in
  15196.      TrapWord) to its corresponding trap name (in S).  It is provided primarily for
  15197.      use with the Disassembler and its address may be passed to InitLookup above for
  15198.      use by this unit's Lookup routine.  Alternatively, there is nothing prohibiting
  15199.      the caller from using it directly for other purposes or by some other lookup
  15200.      proc.
  15201.     
  15202.     Note: The tables in this proc make the size of this proc about 9500 bytes.  The
  15203.          trap names are fully spelled out in upper and lower case.
  15204. */
  15205.  
  15206.  
  15207. æKY ModifyOperand
  15208. æFc DisAsmLookup.h
  15209. æT Function
  15210. æD pascal void ModifyOperand(char *operand);
  15211. æDT ModifyOperand((char *)operand);
  15212. æC 
  15213. /* 
  15214.     Scan an operand string, i.e., the null terminated Pascal string returned by
  15215.     the Disassembler (null MUST be present here) and modify negative hex values to
  15216.     negated positive value. For example, $FFFF(A5) would be modified to -$0001(A5).
  15217.     The operand to be processed is  passed as the function's parameter which is
  15218.     edited "in place" and returned to the caller.
  15219.     
  15220.     This routine is essentially a pattern matcher and attempts to only modify 2, 4,
  15221.     and 8 digit hex strings in the operand that "might" be offsets from a base
  15222.     register.  If the matching tests are passed, the same number of original digits
  15223.     are output (because that indicates a value's size -- byte, word, or long).
  15224.     
  15225.     For a hex string to be modified, the following tests must be passed:
  15226.     
  15227.     • There must have been exactly 2, 4, or 8 digits.
  15228.     
  15229.       Only hex strings $XX, $XXXX, and $XXXXXXXX are possible candidates because
  15230.       that is the only way the Disassembler generates offsets.
  15231.     
  15232.     • Hex string must be delimited by a "(" or a ",".
  15233.     
  15234.       The "(" allows offsets for $XXXX(An,...) and $XX(An,Xn) addressing modes.
  15235.       The comma allows for the MC68020 addressing forms.
  15236.     
  15237.     • The "$X..." must NOT be preceded by a "±".
  15238.     
  15239.       This eliminates the possibility of modifying the offset of a PC-relative
  15240.       addressing mode always generated in the form "*±$XXXX".
  15241.     
  15242.     • The "$X..." must NOT be preceded by a "#".
  15243.     
  15244.       This eliminates modifying immediate data.
  15245.     
  15246.     • Value must be negative.
  15247.     
  15248.       Negative values are the only values we modify.  A value $FFFF is modified to
  15249.       -$0001.
  15250. */
  15251.  
  15252.  
  15253. æKY showMacsBugSymbol
  15254. æFc DisAsmLookup.h
  15255. æT Function
  15256. æD char *showMacsBugSymbol(char *symStart,void *limit,char *operand,short *bytesUsed);
  15257. æDT char myVariable = showMacsBugSymbol((char *)symStart,(void *)limit,(char *)operand,
  15258.     (short *)bytesUsed);
  15259. æC 
  15260. /* 
  15261.     Format a MacsBug symbol as a operand of a DC.B directive.  The first one or two
  15262.     bytes of the symbol are generated as $80+'c' if they have there high high bits
  15263.     set.  All other characters are shown as characters in a string constant.  The
  15264.     pad byte, if present, is one is also shown as $00.
  15265.     
  15266.     This routine is called to check that the bytes pointed to by symStart represent
  15267.     a valid MacsBug symbol.  The symbol must be fully contained in the bytes
  15268.     starting at symStart, up to, but not including the byte pointed to by the limit
  15269.     parameter.
  15270.     
  15271.     When called, showMacsBugSymbol assumes that symStart is pointing at a valid
  15272.     MacsBug symbol as validated by the validMacsBugSymbol or endOfModule routines.
  15273.     As with validMacsBugSymbol, the symbol must be fully contained in the bytes
  15274.     starting at symStart up to, but not including, the byte pointed to by the end
  15275.     parameter.
  15276.     
  15277.     The string is returned in the 'operand' parameter as a null terminated Pascal
  15278.     string.  The function also returns a pointer to this string as its return
  15279.     value (NULL is returned only if the byte pointed to by the limit parameter is
  15280.     reached prior to processing the entire symbol -- which should not happen if
  15281.     properly validated).  The number of bytes used for the symbol is returned in
  15282.     bytesUsed.  Due to the way MacsBug symbols are encoded, bytesUsed may not
  15283.     necessarily be the same as the length of the operand string.
  15284.     
  15285.     A valid MacsBug symbol consists of the characters '_', '%', spaces, digits, and
  15286.     upper/lower case letters in a format determined by the first two bytes of the
  15287.     symbol as described in the validMacsBugSymbol routine.
  15288.     
  15289. */
  15290.  
  15291. æKY validMacsBugSymbol
  15292. æFc DisAsmLookup.h
  15293. æT Function
  15294. æD char *validMacsBugSymbol(char *symStart,void *limit,char *symbol);
  15295. æDT char myVariable = validMacsBugSymbol((char *)symStart,(void *)limit,
  15296.     (char *)symbol);
  15297. æC 
  15298. /* 
  15299.     Check that the bytes pointed to by symStart represents a valid MacsBug symbol.
  15300.     The symbol must be fully contained in the bytes starting at symStart, up to,
  15301.     but not including, the byte pointed to by the limit parameter.
  15302.     
  15303.     If a valid symbol is NOT found, then NULL is returned as the function's result.
  15304.     However, if a valid symbol is found, it is copied to symbol (if it is not NULL)
  15305.     as a null terminated Pascal string, and return a pointer to where we think the
  15306.     FOLLOWING module begins. In the "old style" cases (see below) this will always
  15307.     be 8 or 16 bytes after the input symStart.  For new style Apple Pascal and C
  15308.     cases this will depend on the symbol length, existence of a pad byte, and size
  15309.     of the constant (literal) area.  In all cases, trailing blanks are removed from
  15310.     the symbol.
  15311.     
  15312.     A valid MacsBug symbol consists of the characters '_', '%', spaces, digits, and
  15313.     upper/lower case letters in a format determined by the first two bytes of the
  15314.     symbol as follows:
  15315.     
  15316.      1st byte  | 2nd byte  |  Byte  |
  15317.        Range   |  Range    | Length | Comments
  15318.     ==============================================================================
  15319.      $20 - $7F | $20 - $7F |    8   | "Old style" MacsBug symbol format
  15320.      $A0 - $FF | $20 - $7F |    8   | "Old style" MacsBug symbol format
  15321.     ------------------------------------------------------------------------------
  15322.      $20 - $7F | $80 - $FF |   16   | "Old style" MacApp symbol ab==>b.a
  15323.      $A0 - $FF | $80 - $FF |   16   | "Old style" MacApp symbol ab==>b.a
  15324.     ------------------------------------------------------------------------------
  15325.      $80       | $01 - $FF |    n   | n = 2nd byte       (Apple Compiler symbol)
  15326.      $81 - $9F | $00 - $FF |    m   | m = 1st byte & $7F (Apple Compiler symbol)
  15327.     ==============================================================================
  15328.     
  15329.     The formats are determined by whether bit 7 is set in the first and second
  15330.     bytes.  This bit will removed when we find it or'ed into the first and/or
  15331.     second valid symbol characters.
  15332.     
  15333.     The first two formats in the above table are the basic "old style" (pre-
  15334.     existing) MacsBug formats. The first byte may or may not have bit 7 set the
  15335.     second byte is a valid symbol character.  The first byte (with bit 7 removed)
  15336.     and the next 7 bytes are assumed to comprise the symbol.
  15337.     
  15338.     The second pair of formats are also "old style" formats, but used for MacApp
  15339.     symbols.  Bit 7 set in the second character indicates these formats. The symbol
  15340.     is assumed to be 16 bytes with the second 8 bytes preceding the first 8 bytes
  15341.     in the generated symbol.  For example, 12345678abcdefgh represents the symbol
  15342.     abcdefgh.12345678.
  15343.     
  15344.     The last pair of formats are reserved by Apple and generated by the MPW Pascal
  15345.     and C compilers.  In these cases the value of the first byte is always between
  15346.     $80 and $9F, or with bit 7 removed, between $00 and $1F.  For $00, the second
  15347.     byte is the length of the symbol with that many bytes following the second
  15348.     byte (thus a max length of 255). Values $01 to $1F represent the length itself.
  15349.     A pad byte may follow these variable length cases if the symbol does not end
  15350.     on a word boundary.  Following the symbol and the possible pad byte is a word
  15351.     containing the size of the constants (literals) generated by the compiler.
  15352.     
  15353.     Note that if symStart actually does point to a valid MacsBug symbol, then you
  15354.     may use showMacsBugSymbol to convert the MacsBug symbol bytes to a string that
  15355.     could be used as a DC.B operand for disassembly purposes.  This string
  15356.     explicitly shows the MacsBug symbol encodings.
  15357. */
  15358.  
  15359.  
  15360. æKY DiskInit.h
  15361. æKL DIBadMount
  15362. dibadmount
  15363. DIFormat
  15364. DILoad
  15365. DIUnload
  15366. DIVerify
  15367. dizero
  15368. DIZero
  15369.  
  15370. HFSDefaults
  15371.  
  15372. æKY HFSDefaults
  15373. æFc DiskInit.h
  15374. æT struct
  15375. æD struct HFSDefaults {
  15376.     char sigWord[2]; /* signature word*/
  15377.     long abSize; /* allocation block size in bytes*/
  15378.     long clpSize; /* clump size in bytes*/
  15379.     long nxFreeFN; /* next free file number*/
  15380.     long btClpSize; /* B-Tree clump size in bytes*/
  15381.     short rsrv1; /* reserved*/
  15382.     short rsrv2; /* reserved*/
  15383.     short rsrv3; /* reserved*/
  15384. };
  15385.  
  15386. typedef struct HFSDefaults HFSDefaults;
  15387. æC 
  15388. »Formatting Hierarchical Volumes
  15389.  
  15390. The Disk Initialization Package must set certain volume characteristics when placing
  15391. a hierarchical file directory on a volume. Default values for these volume characteristics
  15392. are stored in the 128K ROM; this section is for advanced programmers who want to
  15393. substitute their own values. The record containing the default values, if defined in
  15394. Pascal, would look like this:
  15395.  
  15396. TYPE  HFSDefaults = PACKED RECORD
  15397.                       sigWord:    ARRAY[1..2] OF CHAR;    {signature word}
  15398.                       abSize:     LONGINT;    {allocation block size in bytes}
  15399.                       clpSize:    LONGINT;    {clump size in bytes}
  15400.                       nxFreeFN:   LONGINT;    {next free file number}
  15401.                       btClpSize:  LONGINT;    {B*-Tree clump size in bytes}
  15402.                       rsrv1:      INTEGER;    {reserved}
  15403.                       rsrv2:      INTEGER;    {reserved}
  15404.                       rsrv3:      INTEGER;    {reserved}
  15405.                     END;
  15406.  
  15407. The default values for these fields are as follows:
  15408.  
  15409.   Field    Default value
  15410.  
  15411.   sigWord     'BD'
  15412.   abSize       0
  15413.   clpSize      4 * abSize
  15414.   nxFreeFN    16
  15415.   btClpSize    0
  15416.  
  15417. To supply your own values for these fields, create a similar, nonrelocatable record
  15418. containing the desired values and place a pointer to it in the global variable FmtDefaults.
  15419. To restore the system defaults, simply clear FmtDefaults.
  15420.  
  15421. The sigWord must equal 'BD' (meaning “big disk”) for the volume to be recognized as a
  15422. hierarchical volume. If the specified allocation block size is 0, the allocation
  15423. block size is calculated according to the size of the volume:
  15424.  
  15425.   abSize = (1 + (volSize in blocks / 64K)) * 512 bytes
  15426.  
  15427. If the specified B*-tree clump size is 0, the clump size for both the catalog and
  15428. extent trees is calculated according to the size of the volume:
  15429.  
  15430.   btClpSize = (volSize in blocks)/128 * 512bytes
  15431.  
  15432. æKY DILoad
  15433. æFc DiskInit.h
  15434. æT Function
  15435. æD pascal void DILoad(void); 
  15436. æDT DILoad()(void);
  15437. æMM
  15438. æRI II-396
  15439. æC 
  15440. Assembly-language note:  The trap macro for the Disk Initialization Package
  15441.                          is _Pack2. The routine selectors are as follows:
  15442.  
  15443.                            diBadMount  .EQU    0
  15444.                            diLoad      .EQU    2
  15445.                            diUnload    .EQU    4
  15446.                            diFormat    .EQU    6
  15447.                            diVerify    .EQU    8
  15448.                            diZero      .EQU    10
  15449.  
  15450. DILoad reads the Disk Initialization Package, and its associated dialog and dialog
  15451. items, from the system resource file into memory and makes them unpurgeable.
  15452.  
  15453. Note:  DIFormat, DIVerify, and DIZero don’t need the dialog, so if you use
  15454.        only these routines you can call the Resource Manager function
  15455.        GetResource to read just the package resource into memory (and
  15456.        the Memory Manager procedure HNoPurge to make it unpurgeable).
  15457.  
  15458. æKY DIUnload
  15459. æFc DiskInit.h
  15460. æT Function
  15461. æD pascal void DIUnload(void); 
  15462. æDT DIUnload()(void);
  15463. æMM
  15464. æRI II-396
  15465. æC  
  15466. Assembly-language note:  The trap macro for the Disk Initialization Package
  15467.                          is _Pack2. The routine selectors are as follows:
  15468.  
  15469.                            diBadMount  .EQU    0
  15470.                            diLoad      .EQU    2
  15471.                            diUnload    .EQU    4
  15472.                            diFormat    .EQU    6
  15473.                            diVerify    .EQU    8
  15474.                            diZero      .EQU    10
  15475.  
  15476. DIUnload makes the Disk Initialization Package (and its associated dialog and dialog
  15477. items) purgeable.
  15478.  
  15479. æKY DIBadMount
  15480. æFc DiskInit.h
  15481. æT Function
  15482. æD pascal short DIBadMount(Point where,long evtMessage); 
  15483. æDT short myVariable = DIBadMount((Point) where,(long) evtMessage);
  15484. æRI DIBadMount function  II-396, N70-1, P-34, 168
  15485.  
  15486. æC 
  15487. Assembly-language note:  The trap macro for the Disk Initialization Package
  15488.                          is _Pack2. The routine selectors are as follows:
  15489.  
  15490.                            diBadMount  .EQU    0
  15491.                            diLoad      .EQU    2
  15492.                            diUnload    .EQU    4
  15493.                            diFormat    .EQU    6
  15494.                            diVerify    .EQU    8
  15495.                            diZero      .EQU    10
  15496.  
  15497. Call DIBadMount when a disk-inserted event occurs if the result code in the high-order
  15498. word of the associated event message indicates an error (that is, the result code is
  15499. other than noErr). Given the event message in evtMessage, DIBadMount evaluates the
  15500. result code and either ejects the disk or lets the user initialize and name it. The
  15501. low-order word of the event message contains the drive number. The where parameter
  15502. specifies the location (in global coordinates) of the top left corner of the dialog
  15503. box displayed by DIBadMount.
  15504.  
  15505. If the result code passed is extFSErr, memFullErr, nsDrvErr, paramErr, or volOnLinErr,
  15506. DIBadMount simply ejects the disk from the drive and returns the result code. If the
  15507. result code ioErr, badMDBErr, or noMacDskErr is passed, the error can be corrected by
  15508. initializing the disk; DIBadMount displays a dialog box that describes the problem
  15509. and asks whether the user wants to initialize the disk. For the result code ioErr,
  15510. the dialog box shown in Figure 1 is displayed. (This happens if the disk is brand
  15511. new.) For badMDBErr and noMacDskErr, DIBadMount displays a similar dialog box in
  15512. which the description of the problem is “This disk is damaged” and “This is not a
  15513. Macintosh disk”, respectively.
  15514.  
  15515. •••Refer to Figure 1.•••
  15516.  
  15517. Figure 1–Disk Initialization Dialog for IOErr
  15518.  
  15519. Note:  Before presenting the disk initialization dialog, DIBadMount checks
  15520.        whether the drive contains an already mounted volume; if so, it ejects
  15521.        the disk and returns 2 as its result. This will happen rarely and may
  15522.        reflect an error in your program (for example, you forgot to call
  15523.        DILoad and the user had to switch to the disk containing the system
  15524.        resource file).
  15525.  
  15526. If the user responds to the disk initialization dialog by clicking the Eject button,
  15527. DIBadMount ejects the disk and returns 1 as its result. If the Initialize button is
  15528. clicked, a box displaying the message “Initializing
  15529. disk...” appears, and DIBadMount attempts to initialize the disk. If initialization
  15530. fails, the disk is ejected and the user is informed as shown in Figure 2; after the
  15531. user clicks OK, DIBadMount returns a negative result code ranging from firstDskErr to
  15532. lastDskErr, indicating that a low-level disk error occurred.
  15533.  
  15534. •••Refer to Figure 2.•••
  15535.  
  15536. Figure 2–Initialization Failure Dialog
  15537.  
  15538. If the disk is successfully initialized, the dialog box in Figure 3 appears. After
  15539. the user names the disk and clicks OK, DIBadMount mounts the volume by calling the
  15540. File Manager function MountVol and returns MountVol’s result code
  15541. (noErr if no error occurs).
  15542.  
  15543. •••Refer to Figure 3.•••
  15544.  
  15545. Figure 3–Dialog for Naming a Disk
  15546.  
  15547. Result codes    noErr               No error
  15548.                 extFSErr            External file system
  15549.                 memFullErr          Not enough room in heap zone
  15550.                 nsDrvErr            No such drive
  15551.                 paramErr            Bad drive number
  15552.                 volOnLinErr         Volume already on-line
  15553.                 firstDskErr         Low-level disk error
  15554.                 through lastDskErr
  15555.  
  15556. Other results   1                   User clicked Eject
  15557.                 2                   Mounted volume in drive
  15558.  
  15559. æKY dibadmount
  15560. æFc DiskInit.h
  15561. æT Function
  15562. æD OSErr dibadmount(Point *where,long evtMessage); 
  15563. æDT OSErr myVariable = dibadmount((Point *) where,(long) evtMessage);
  15564. æC 
  15565. Assembly-language note:  The trap macro for the Disk Initialization Package
  15566.                          is _Pack2. The routine selectors are as follows:
  15567.  
  15568.                            diBadMount  .EQU    0
  15569.                            diLoad      .EQU    2
  15570.                            diUnload    .EQU    4
  15571.                            diFormat    .EQU    6
  15572.                            diVerify    .EQU    8
  15573.                            diZero      .EQU    10
  15574.  
  15575. Call DIBadMount when a disk-inserted event occurs if the result code in the high-order
  15576. word of the associated event message indicates an error (that is, the result code is
  15577. other than noErr). Given the event message in evtMessage, DIBadMount evaluates the
  15578. result code and either ejects the disk or lets the user initialize and name it. The
  15579. low-order word of the event message contains the drive number. The where parameter
  15580. specifies the location (in global coordinates) of the top left corner of the dialog
  15581. box displayed by DIBadMount.
  15582.  
  15583. If the result code passed is extFSErr, memFullErr, nsDrvErr, paramErr, or volOnLinErr,
  15584. DIBadMount simply ejects the disk from the drive and returns the result code. If the
  15585. result code ioErr, badMDBErr, or noMacDskErr is passed, the error can be corrected by
  15586. initializing the disk; DIBadMount displays a dialog box that describes the problem
  15587. and asks whether the user wants to initialize the disk. For the result code ioErr,
  15588. the dialog box shown in Figure 1 is displayed. (This happens if the disk is brand
  15589. new.) For badMDBErr and noMacDskErr, DIBadMount displays a similar dialog box in
  15590. which the description of the problem is “This disk is damaged” and “This is not a
  15591. Macintosh disk”, respectively.
  15592.  
  15593. •••Refer to Figure 1.•••
  15594.  
  15595. Figure 1–Disk Initialization Dialog for IOErr
  15596.  
  15597. Note:  Before presenting the disk initialization dialog, DIBadMount checks
  15598.        whether the drive contains an already mounted volume; if so, it ejects
  15599.        the disk and returns 2 as its result. This will happen rarely and may
  15600.        reflect an error in your program (for example, you forgot to call
  15601.        DILoad and the user had to switch to the disk containing the system
  15602.        resource file).
  15603.  
  15604. If the user responds to the disk initialization dialog by clicking the Eject button,
  15605. DIBadMount ejects the disk and returns 1 as its result. If the Initialize button is
  15606. clicked, a box displaying the message “Initializing
  15607. disk...” appears, and DIBadMount attempts to initialize the disk. If initialization
  15608. fails, the disk is ejected and the user is informed as shown in Figure 2; after the
  15609. user clicks OK, DIBadMount returns a negative result code ranging from firstDskErr to
  15610. lastDskErr, indicating that a low-level disk error occurred.
  15611.  
  15612. •••Refer to Figure 2.•••
  15613.  
  15614. Figure 2–Initialization Failure Dialog
  15615.  
  15616. If the disk is successfully initialized, the dialog box in Figure 3 appears. After
  15617. the user names the disk and clicks OK, DIBadMount mounts the volume by calling the
  15618. File Manager function MountVol and returns MountVol’s result code
  15619. (noErr if no error occurs).
  15620.  
  15621. •••Refer to Figure 3.•••
  15622.  
  15623. Figure 3–Dialog for Naming a Disk
  15624.  
  15625. Result codes    noErr               No error
  15626.                 extFSErr            External file system
  15627.                 memFullErr          Not enough room in heap zone
  15628.                 nsDrvErr            No such drive
  15629.                 paramErr            Bad drive number
  15630.                 volOnLinErr         Volume already on-line
  15631.                 firstDskErr         Low-level disk error
  15632.                 through lastDskErr
  15633.  
  15634. Other results   1                   User clicked Eject
  15635.                 2                   Mounted volume in drive
  15636.  
  15637. æKY DIFormat
  15638. æFc DiskInit.h
  15639. æT Function
  15640. æD pascal OSErr DIFormat(short drvNum); 
  15641. æDT OSErr myVariable = DIFormat((short) drvNum);
  15642. æMM
  15643. æRI II-398
  15644. æC 
  15645. Assembly-language note:  The trap macro for the Disk Initialization Package
  15646.                          is _Pack2. The routine selectors are as follows:
  15647.  
  15648.                            diBadMount  .EQU    0
  15649.                            diLoad      .EQU    2
  15650.                            diUnload    .EQU    4
  15651.                            diFormat    .EQU    6
  15652.                            diVerify    .EQU    8
  15653.                            diZero      .EQU    10
  15654.  
  15655. DIFormat formats the disk in the drive specified by the given drive number and returns
  15656. a result code indicating whether the formatting was completed successfully or failed.
  15657. Formatting a disk consists of writing special information onto it so that the Disk
  15658. Driver can read from and write to the disk.
  15659.  
  15660. Result codes    noErr               No error
  15661.                 firstDskErr         Low-level disk error
  15662.                 through lastDskErr
  15663.  
  15664. æKY DIVerify
  15665. æFc DiskInit.h
  15666. æT Function
  15667. æD pascal OSErr DIVerify(short drvNum); 
  15668. æDT OSErr myVariable = DIVerify((short) drvNum);
  15669. æMM
  15670. æRI II-398
  15671. æC 
  15672. Assembly-language note:  The trap macro for the Disk Initialization Package
  15673.                          is _Pack2. The routine selectors are as follows:
  15674.  
  15675.                            diBadMount  .EQU    0
  15676.                            diLoad      .EQU    2
  15677.                            diUnload    .EQU    4
  15678.                            diFormat    .EQU    6
  15679.                            diVerify    .EQU    8
  15680.                            diZero      .EQU    10
  15681.  
  15682. DIVerify verifies the format of the disk in the drive specified by the given drive
  15683. number; it reads each bit from the disk and returns a result code indicating whether
  15684. all bits were read successfully or not. DIVerify doesn’t affect the contents of the
  15685. disk itself.
  15686.  
  15687. Result codes    noErr               No error
  15688.                 firstDskErr         Low-level disk error
  15689.                 through lastDskErr
  15690.  
  15691. æKY DIZero
  15692. æFc DiskInit.h
  15693. æT Function
  15694. æD pascal OSErr DIZero(short drvNum,const Str255 volName); 
  15695. æDT OSErr myVariable = DIZero((short) drvNum,(const Str255) volName);
  15696. æMM
  15697. æRT 70
  15698. æRI II-399, N70-2
  15699. æC 
  15700. Assembly-language note:  The trap macro for the Disk Initialization Package
  15701.                          is _Pack2. The routine selectors are as follows:
  15702.  
  15703.                            diBadMount  .EQU    0
  15704.                            diLoad      .EQU    2
  15705.                            diUnload    .EQU    4
  15706.                            diFormat    .EQU    6
  15707.                            diVerify    .EQU    8
  15708.                            diZero      .EQU    10
  15709.  
  15710. On the unmounted volume in the drive specified by the given drive number, DIZero
  15711. writes the volume information, a block map, and a file directory as for a volume with
  15712. no files; the volName parameter specifies the volume name to be included in the
  15713. volume information. This is the last step in initialization
  15714. (after formatting and verifying) and makes any files that are already on the volume
  15715. permanently inaccessible. If the operation fails, DIZero returns a result code indicating
  15716. that a low-level disk error occurred; otherwise, it mounts the volume by calling the
  15717. File Manager function MountVol and returns MountVol’s result code (noErr if no error
  15718. occurs).
  15719.  
  15720. Result codes    noErr              No error
  15721.                 badMDBErr          Bad master directory block
  15722.                 extFSErr           External file system
  15723.                 ioErr              I/O error
  15724.                 memFullErr         Not enough room in heap zone
  15725.                 noMacDskErr        Not a Macintosh disk
  15726.                 nsDrvErr           No such drive
  15727.                 paramErr           Bad drive number
  15728.                 volOnLinErr        Volume already on-line
  15729.                 firstDskErr        Low-level disk error
  15730.                 through lastDskErr
  15731.  
  15732. æKY dizero
  15733. æFc DiskInit.h
  15734. æT Function
  15735. æD OSErr dizero(short drvnum,char *volName); 
  15736. æDT OSErr myVariable = dizero((short) drvnum,(char *) volName);
  15737. æC 
  15738.  
  15739.  
  15740. æKY Disks.h
  15741. æKL DiskEject
  15742. DriveStatus
  15743. SetTagBuffer
  15744.  
  15745. DrvSts
  15746. DrvSts2
  15747.  
  15748. æKY DrvSts
  15749. æFc Disks.h
  15750. æT struct
  15751. æD struct DrvSts {
  15752.     short track;
  15753.     char writeProt;
  15754.     char diskInPlace;
  15755.     char installed;
  15756.     char sides;
  15757.     QElemPtr qLink;
  15758.     short qType;
  15759.     short dQDrive;
  15760.     short dQRefNum;
  15761.     short dQFSID;
  15762.     char twoSideFmt;
  15763.     char needsFlush;
  15764.     short diskErrs;
  15765. };
  15766.  
  15767. typedef struct DrvSts DrvSts;
  15768. æC 
  15769.  
  15770. æKY DrvSts2
  15771. æFc Disks.h
  15772. æT struct
  15773. æD struct DrvSts2 {
  15774.     short track;
  15775.     char writeProt;
  15776.     char diskInPlace;
  15777.     char installed;
  15778.     char sides;
  15779.     QElemPtr qLink;
  15780.     short qType;
  15781.     short dQDrive;
  15782.     short dQRefNum;
  15783.     short dQFSID;
  15784.     short driveSize;
  15785.     short driveS1;
  15786.     short driveType;
  15787.     short driveManf;
  15788.     short driveChar;
  15789.     char driveMisc;
  15790. };
  15791.  
  15792. typedef struct DrvSts2 DrvSts2;
  15793. æC 
  15794.  
  15795. æKY DiskEject
  15796. æFc Disks.h
  15797. æT Function
  15798. æD pascal OSErr DiskEject(short drvNum); 
  15799. æDT OSErr myVariable = DiskEject((short) drvNum);
  15800. æMM
  15801. æRI II-214
  15802. æC 
  15803. [Not in ROM]
  15804.  
  15805. Assembly-language note:  DiskEject is equivalent to a Control call with
  15806.                          csCode equal to the global constant ejectCode.
  15807.  
  15808. DiskEject ejects the disk from the internal drive if drvNum is 1, or from the external
  15809. drive if drvNum is 2.
  15810.  
  15811. Result codes    noErr       No error
  15812.                 nsDrvErr    No such drive
  15813.  
  15814. æKY SetTagBuffer
  15815. æFc Disks.h
  15816. æT Function
  15817. æD pascal OSErr SetTagBuffer(Ptr buffPtr); 
  15818. æDT OSErr myVariable = SetTagBuffer((Ptr) buffPtr);
  15819. æMM
  15820. æRI II-214
  15821. æC 
  15822. [Not in ROM]
  15823.  
  15824. Assembly-language note:  SetTagBuffer is equivalent to a Control call with
  15825.                          csCode equal to the global constant tgBuffCode.
  15826.  
  15827. An application can change the information used in the file tags buffer by calling
  15828. SetTagBuffer. The buffPtr parameter points to a buffer that contains the information
  15829. to be used. If buffPtr is NIL, the information in the file tags buffer isn’t changed.
  15830.  
  15831. If buffPtr isn’t NIL, every time the Disk Driver reads a sector from the disk, it
  15832. stores the file tags in the file tags buffer and in the buffer pointed to by buffPtr.
  15833. Every time the Disk Driver writes a sector onto the disk, it reads 12 bytes from the
  15834. buffer pointed to by buffPtr, places them in the file tags buffer, and then writes
  15835. them onto the disk.
  15836.  
  15837. The contents of the buffer pointed to by buffPtr are overwritten at the end of every
  15838. read request (which can be composed of a number of sectors) instead of at the end of
  15839. every sector. Each read request places 12 bytes in the buffer for each sector, always
  15840. beginning at the start of the buffer. This way an application can examine the file
  15841. tags for a number of sequentially read sectors. If a read request is composed of a
  15842. number of sectors, the Disk Driver places 12 bytes in the buffer for each sector. For
  15843. example, for a read request of five sectors, the Disk Driver will place 60 bytes in
  15844. the buffer.
  15845.  
  15846. Result codes    noErr    No error
  15847.  
  15848. æKY DriveStatus
  15849. æFc Disks.h
  15850. æT Function
  15851. æD pascal OSErr DriveStatus(short drvNum,DrvSts *status); 
  15852. æDT OSErr myVariable = DriveStatus((short) drvNum,(DrvSts *) status);
  15853. æMM
  15854. æRI II-215
  15855. æC 
  15856. [Not in ROM]
  15857.  
  15858. Assembly-language note:  DriveStatus is equivalent to a Status call with
  15859.                          csCode equal to the global constant drvStsCode;
  15860.                          status is returned in csParam through csParam+21.
  15861.  
  15862. DriveStatus returns information about the internal drive if drvNum is 1, or about the
  15863. external drive if drvNum is 2. The information is returned in a record of type DrvSts:
  15864.  
  15865. TYPE  DrvSts = RECORD
  15866.                  track:        INTEGER;     {current track}
  15867.                  writeProt:    SignedByte;  {bit 7=1 if volume is locked}
  15868.                  diskInPlace:  SignedByte;  {disk in place}
  15869.                  installed:    SignedByte;  {drive installed}
  15870.                  sides:        SignedByte;  {bit 7=0 if single-side drive}
  15871.                  qLink:        QElemPtr;    {next queue entry}
  15872.                  qType:        INTEGER;     {reserved for future use}
  15873.                  dQDrive:      INTEGER;     {drive number}
  15874.                  dQRefNum:     INTEGER;     {driver reference number}
  15875.                  dQFSID:       INTEGER;     {file-system identifier}
  15876.                  twoSideFmt:   SignedByte;  {-1 if two-sided disk}
  15877.                  needsFlush:   SignedByte;  {reserved for future use}
  15878.                  diskErrs:     INTEGER      {error count}
  15879.                END;
  15880.  
  15881. The diskInPlace field is 0 if there’s no disk in the drive, 1 or 2 if there is a disk
  15882. in the drive, or –4 to –1 if the disk was ejected in the last 1.5 seconds. The installed
  15883. field is 1 if the drive is connected to the Macintosh, 0 if the drive might be connected
  15884. to the Macintosh, and –1 if the drive isn’t installed. The value of twoSideFmt is
  15885. valid only when diskInPlace=2. The value of diskErrs is incremented every time an
  15886. error occurs internally within the Disk Driver.
  15887.  
  15888. Result codes    noErr       No error
  15889.                 nsDrvErr    No such drive
  15890.  
  15891.  
  15892. æKY Editions.h
  15893. æKL AssociateSection
  15894. CallEditionOpenerProc
  15895. CallFormatIOProc
  15896. CloseEdition
  15897. CreateEditionContainerFile
  15898. DeleteEditionContainerFile
  15899. EditionHasFormat
  15900. FindEditionContainerDialog
  15901. GetEditionFormatMark
  15902. GetEditionInfo
  15903. GetEditionOpenerProc
  15904. GetLastEditionContainerUsed
  15905. GetStandardFormats
  15906. GotoPublisherSection
  15907. InitEditionPack
  15908. IsRegisterSection
  15909. NewPublisherDialog
  15910. NewPublisherExpDialog
  15911. NewSection
  15912. NewSubscriberDialog
  15913. NewSubscriberExpDialog
  15914. OpenEdition
  15915. OpenNewEdition
  15916. ReadEdition
  15917. RegisterSection
  15918. SectionOptionsDialog
  15919. SectionOptionsExpDialog
  15920. SetEditionFormatMark
  15921. SetEditionOpenerProc
  15922. UnRegisterSection
  15923. WriteEdition
  15924.  
  15925. EditionContainerSpec
  15926. EditionInfoRecord
  15927. EditionOpenerParamBlock
  15928. EditionOpenerProcPtr
  15929. EditionOpenerVerb
  15930. EditionRefNum
  15931. eoCanSubscribe
  15932. eoClose
  15933. eoCloseNew
  15934. eoOpen
  15935. eoOpenNew
  15936. ExpDlgHookProcPtr
  15937. ExpModalFilterProcPtr
  15938. FormatIOParamBlock
  15939. FormatIOProcPtr
  15940. FormatIOVerb
  15941. FormatType
  15942. ioHasFormat
  15943. ioNewFormat
  15944. ioReadFormat
  15945. ioWriteFormat
  15946. kFormatLengthUnknown
  15947. kFormatListFormat
  15948. kPartNumberUnknown
  15949. kPartsNotUsed
  15950. kPreviewFormat
  15951. kPreviewHeight
  15952. kPreviewWidth
  15953. kPublisherDocAliasFormat
  15954. NewPublisherReply
  15955. NewSubscriberReply
  15956. pumOnSave
  15957. pumSuspend
  15958. rSectionType
  15959. sectionCancelMsgID
  15960. sectionEventMsgClass
  15961. SectionHandle
  15962. SectionOptionsReply
  15963. SectionPtr
  15964. sectionReadMsgID
  15965. SectionRecord
  15966. sectionScrollMsgID
  15967. SectionType
  15968. sectionWriteMsgID
  15969. stPublisher
  15970. stSubscriber
  15971. sumAutomatic
  15972. sumOnRequestOnly
  15973. TimeStamp
  15974. UpdateMode
  15975.  
  15976. æKY rSectionType
  15977. æFc Editions.h
  15978. æT #define
  15979. æD 
  15980. /*  resource types  */
  15981.  
  15982. #define rSectionType 'sect' /* ResType of saved SectionRecords */
  15983. æC 
  15984.  
  15985. æKY stSubscriber
  15986. æFc Editions.h
  15987. æT #define
  15988. æD 
  15989. /*  ssection types  */
  15990.  
  15991. #define stSubscriber 0x01
  15992. æC 
  15993.  
  15994. æKY stPublisher
  15995. æFc Editions.h
  15996. æT #define
  15997. æD #define stPublisher 0x0A
  15998. æC 
  15999.  
  16000. æKY sumAutomatic
  16001. æFc Editions.h
  16002. æT #define
  16003. æD 
  16004. /*  update modes  */
  16005.  
  16006. #define sumAutomatic 0 /* subscriber update mode - Automatic        */
  16007. æC 
  16008.  
  16009. æKY sumOnRequestOnly
  16010. æFc Editions.h
  16011. æT #define
  16012. æD #define sumOnRequestOnly 1 /* subscriber update mode - OnRequestOnly    */
  16013. æC 
  16014.  
  16015. æKY pumOnSave
  16016. æFc Editions.h
  16017. æT #define
  16018. æD #define pumOnSave 0 /* publisher update mode - OnSave            */
  16019. æC 
  16020.  
  16021. æKY pumSuspend
  16022. æFc Editions.h
  16023. æT #define
  16024. æD #define pumSuspend 1 /* publisher update mode - OnRequestOnly    */
  16025. æC 
  16026.  
  16027. æKY kPartsNotUsed
  16028. æFc Editions.h
  16029. æT #define
  16030. æD #define kPartsNotUsed 0
  16031. æC 
  16032.  
  16033. æKY kPartNumberUnknown
  16034. æFc Editions.h
  16035. æT #define
  16036. æD #define kPartNumberUnknown (-1)
  16037. æC 
  16038.  
  16039. æKY kPreviewWidth
  16040. æFc Editions.h
  16041. æT #define
  16042. æD #define kPreviewWidth 120
  16043. æC 
  16044.  
  16045. æKY kPreviewHeight
  16046. æFc Editions.h
  16047. æT #define
  16048. æD #define kPreviewHeight 120
  16049. æC 
  16050.  
  16051. æKY kPublisherDocAliasFormat
  16052. æFc Editions.h
  16053. æT #define
  16054. æD #define kPublisherDocAliasFormat 'alis'
  16055. æC 
  16056.  
  16057. æKY kPreviewFormat
  16058. æFc Editions.h
  16059. æT #define
  16060. æD #define kPreviewFormat 'prvw'
  16061. æC 
  16062.  
  16063. æKY kFormatListFormat
  16064. æFc Editions.h
  16065. æT #define
  16066. æD #define kFormatListFormat 'fmts'
  16067. æC 
  16068.  
  16069. æKY kFormatLengthUnknown
  16070. æFc Editions.h
  16071. æT #define
  16072. æD #define kFormatLengthUnknown (-1)
  16073. æC 
  16074.  
  16075. æKY sectionEventMsgClass
  16076. æFc Editions.h
  16077. æT #define
  16078. æD 
  16079. /*  the following fields are private and set up by RegisterSection                    
  16080.  
  16081.     Section events now arrive in the message buffer using the new AppleEvent format.
  16082.     The direct object parameter is an aeTemporaryIDParamType ('tid '). The temporary
  16083.     ID's type is rSectionType ('sect') and the 32-bit value is a SectionHandle.
  16084.  
  16085.  */
  16086.  
  16087. #define sectionEventMsgClass 'sect'
  16088. æC 
  16089.  
  16090. æKY sectionReadMsgID
  16091. æFc Editions.h
  16092. æT #define
  16093. æD #define sectionReadMsgID 'read'
  16094. æC 
  16095.  
  16096. æKY sectionWriteMsgID
  16097. æFc Editions.h
  16098. æT #define
  16099. æD #define sectionWriteMsgID 'writ'
  16100. æC 
  16101.  
  16102. æKY sectionScrollMsgID
  16103. æFc Editions.h
  16104. æT #define
  16105. æD #define sectionScrollMsgID 'scrl'
  16106. æC 
  16107.  
  16108. æKY sectionCancelMsgID
  16109. æFc Editions.h
  16110. æT #define
  16111. æD #define sectionCancelMsgID 'cncl'
  16112. æC 
  16113.  
  16114. æKY FormatIOVerb
  16115. ioHasFormat
  16116. ioReadFormat
  16117. ioNewFormat
  16118. ioWriteFormat
  16119. æFc Editions.h
  16120. æT enum
  16121. æD enum {ioHasFormat,ioReadFormat,ioNewFormat,ioWriteFormat};
  16122. typedef unsigned char FormatIOVerb;
  16123. æC 
  16124.  
  16125. æKY EditionOpenerVerb
  16126. eoOpen
  16127. eoClose
  16128. eoOpenNew
  16129. eoCloseNew
  16130. eoCanSubscribe
  16131.  
  16132. æFc Editions.h
  16133. æT enum
  16134. æD enum {eoOpen,eoClose,eoOpenNew,eoCloseNew,eoCanSubscribe};
  16135. typedef unsigned char EditionOpenerVerb;
  16136. æC 
  16137.  
  16138. æKY UpdateMode
  16139. æFc Editions.h
  16140. æT typedef
  16141. æD typedef short UpdateMode; /* sumAutomatic, pumSuspend, etc */
  16142. æC 
  16143.  
  16144. æKY SectionType
  16145. æFc Editions.h
  16146. æT typedef
  16147. æD typedef char SectionType; /* one byte, stSubscriber or stPublisher */
  16148. æC 
  16149.  
  16150. æKY TimeStamp
  16151. æFc Editions.h
  16152. æT typedef
  16153. æD typedef unsigned long TimeStamp; /* seconds since 1904 */
  16154. æC 
  16155.  
  16156. æKY FormatType
  16157. æFc Editions.h
  16158. æT typedef
  16159. æD typedef unsigned long FormatType; /* similar to ResType */
  16160. æC 
  16161.  
  16162. æKY EditionRefNum
  16163. æFc Editions.h
  16164. æT typedef
  16165. æD typedef Handle EditionRefNum; /* used in Edition I/O */
  16166. æC 
  16167.  
  16168. æKY ExpModalFilterProcPtr
  16169. æFc Editions.h
  16170. æT typedef
  16171. æD typedef pascal Boolean (*ExpModalFilterProcPtr) (DialogPtr theDialog, EventRecord *theEvent,
  16172.  short itemOffset, short *itemHit, Ptr yourDataPtr);
  16173. æC 
  16174.  
  16175. æKY ExpDlgHookProcPtr
  16176. æFc Editions.h
  16177. æT typedef
  16178. æD typedef pascal short (*ExpDlgHookProcPtr) (short itemOffset,
  16179.   short itemHit, DialogPtr theDialog, Ptr yourDataPtr);
  16180. æC 
  16181.  
  16182. æKY FormatIOProcPtr
  16183. æFc Editions.h
  16184. æT typedef
  16185. æD typedef pascal short (*FormatIOProcPtr) (FormatIOVerb selector, FormatIOParamBlock *PB);
  16186. æC 
  16187.  
  16188. æKY EditionOpenerProcPtr
  16189. æFc Editions.h
  16190. æT typedef
  16191. æD typedef pascal short (*EditionOpenerProcPtr) (EditionOpenerVerb selector, FormatIOParamBlock *PB);
  16192. æC 
  16193.  
  16194. æKY SectionRecord
  16195. SectionPtr
  16196. SectionHandle
  16197. æFc Editions.h
  16198. æT struct
  16199. æD struct SectionRecord {
  16200.     signed char version; /* always 0x01 in system 7.0 */
  16201.     SectionType kind; /* stSubscriber or stPublisher */
  16202.     UpdateMode mode; /* auto or manual */
  16203.     TimeStamp mdDate; /* last change in document */
  16204.     long sectionID; /* app. specific, unique per document */
  16205.     long refCon; /* application specific */
  16206.     AliasHandle alias; /* handle to Alias Record */
  16207.     long subPart; /* which part of container file */
  16208.     struct SectionRecord **nextSection; /* for linked list of app's Sections */
  16209.     Handle controlBlock; /* used internally */
  16210.     EdtionRefNum refNum; /* used internally */
  16211. };
  16212.  
  16213. typedef struct SectionRecord SectionRecord;
  16214. typedef SectionRecord *SectionPtr, **SectionHandle;
  16215.  
  16216. æC 
  16217.  
  16218. æKY EditionContainerSpec
  16219. æFc Editions.h
  16220. æT struct
  16221. æD struct EditionContainerSpec {
  16222.     CanonicalFileSpec theFile;
  16223.     Short theFileScript;
  16224.     long thePart;
  16225.     Str31 thePartName;
  16226.     Short thePartScript;
  16227. };
  16228.  
  16229. typedef struct EditionContainerSpec EditionContainerSpec;
  16230. æC 
  16231.  
  16232. æKY EditionInfoRecord
  16233. æFc Editions.h
  16234. æT struct
  16235. æD struct EditionInfoRecord {
  16236.     TimeStamp crDate; /* date EditionContainer was created */
  16237.     TimeStamp mdDate; /* date of last change */
  16238.     OSType fdCreator; /* file creator */
  16239.     OSType fdType; /* file type */
  16240.     EditionContainerSpec container; /* the Edition */
  16241. };
  16242.  
  16243. typedef struct EditionInfoRecord EditionInfoRecord;
  16244. æC 
  16245.  
  16246. æKY NewPublisherReply
  16247. æFc Editions.h
  16248. æT struct
  16249. æD struct NewPublisherReply {
  16250.     Boolean canceled; /* O */
  16251.     Boolean replacing ;
  16252.     Boolean usePart; /* I */
  16253.     Handle preview; /* I */
  16254.     FormatType previewFormat; /* I */
  16255.     EditionContainerSpec container; /* I/O */
  16256. };
  16257.  
  16258. typedef struct NewPublisherReply NewPublisherReply;
  16259. æC 
  16260.  
  16261. æKY NewSubscriberReply
  16262. æFc Editions.h
  16263. æT struct
  16264. æD struct NewSubscriberReply {
  16265.     Boolean canceled; /* O */
  16266.     EditionContainerSpec container; /* I/O */
  16267. };
  16268.  
  16269. typedef struct NewSubscriberReply NewSubscriberReply;
  16270. æC 
  16271.  
  16272. æKY SectionOptionsReply
  16273. æFc Editions.h
  16274. æT struct
  16275. æD struct SectionOptionsReply {
  16276.     Boolean canceled; /* O */
  16277.     Boolean changed; /* O */
  16278.     SectionHandle sectionH; /* I */
  16279.     ResType action; /* O */
  16280. };
  16281.  
  16282. typedef struct SectionOptionsReply SectionOptionsReply;
  16283. æC 
  16284.  
  16285. æKY FormatIOParamBlock
  16286. æFc Editions.h
  16287. æT struct
  16288. æD struct FormatIOParamBlock {
  16289.     long ioRefNum;
  16290.     FormatType format;
  16291.     long formatIndex;
  16292.     unsigned long offset;
  16293.     Ptr buffPtr;
  16294.     unsigned long buffLen;
  16295. };
  16296.  
  16297. typedef struct FormatIOParamBlock FormatIOParamBlock;
  16298. æC 
  16299.  
  16300. æKY EditionOpenerParamBlock
  16301. æFc Editions.h
  16302. æT struct
  16303. æD struct EditionOpenerParamBlock {
  16304.     EditionInfoRecord info;
  16305.     SectionRecord **sectionH;
  16306.     CanonicalFileSpec *document;
  16307.     OSType fdCreator;
  16308.     long ioRefNum;
  16309.     FormatIOProcPtr ioProc;
  16310.     Boolean success;
  16311. };
  16312.  
  16313. typedef struct EditionOpenerParamBlock EditionOpenerParamBlock;
  16314. æC 
  16315.  
  16316. æKY InitEditionPack
  16317. æFc Editions.h
  16318. æT Function
  16319. æTN A82D
  16320. æD pascal OSErr InitEditionPack(void)
  16321.     = {0x3F3C,0x0010,0x303C,0x0100,0xA82D}; 
  16322. æDT OSErr myVariable = InitEditionPack()(void);
  16323. æC 
  16324. You use the InitEditionPack function to initialize the Edition Manager. Before
  16325. calling this funciton, be sure to determine if the Edition Manager is available
  16326. on your system using the Gestalt function.
  16327.  
  16328. The InitEditionPack function returns an error if the pack could not be loaded or
  16329. is an old version. If the InitEditionPack does not return noErr, there is not
  16330. enough system heap to load the package.
  16331.  
  16332. Result codes
  16333. noErr                   0  No error
  16334. editionMgrInitErr    -450  Could not load package
  16335. MemError                   NewHandle errors
  16336. ResError                   GetResource errors
  16337.  
  16338. æKY NewSection
  16339. æFc Editions.h
  16340. æT Function
  16341. æTN A82D
  16342. æD pascal OSErr NewSection(const EditionContinerSpec *container,const CanonicalFileSpec *sectionDocument,
  16343.     SectionType kind,long sectionID,UpdateMode initalMode,SectionHandle *sectionH)
  16344.     = {0x303C,0x0A02,0xA82D}; 
  16345. æDT OSErr myVariable = NewSection((const EditionContinerSpec *) container,(const CanonicalFileSpec *) sectionDocument,()
  16346.     SectionType kind,(long) sectionID,(UpdateMode) initalMode,(SectionHandle *) sectionH);
  16347. æC 
  16348. You use the NewSection routine to create a new section (either publisher or
  16349. subscriber), and alias record from the sectionDocument (document that contains a
  16350. section) to the edition container. The NewSection function allocates two
  16351. handles; one handle for the section record and another handle for the alias
  16352. record.
  16353.  
  16354. The container parameter is the name of the file which holds the edition.The
  16355. sectionDocument parameter is the file name (in canonical form) of the document
  16356. that contains section. The sectionDocument parameter can be NIL if your current
  16357. document has never been saved. If so, remember to call the AssociateSection
  16358. function when the user finally saves the document to update the alias record of
  16359. a registered section.
  16360.  
  16361. The kind parameter designates the type of section (publisher or subscriber)
  16362. being created. 
  16363.  
  16364. Identify the section with a unique number in the sectionID parameter.
  16365.  
  16366. The initialMode parameter contains the update mode for the section. For
  16367. publishers, this is either the constant pumOnSave or pumSuspend and for
  16368. subscribers this is either sumAutomatic or sumOnRequestOnly.
  16369.  
  16370. If the NewSection function fails, the sectionH parameter is set to NIL. If the
  16371. function is successful, sectionH contains the handle to the allocated section
  16372. record.
  16373.  
  16374. Result codes
  16375. noErr                    0  No error
  16376. editionMgrInitErr     -450  Manager not init’ed
  16377. badSubPartErr         -454  Bad container spec
  16378. badSectionErr         -451  Not valid SectionType
  16379. multiplePublisherWrn  -460  Already is a publisher
  16380. MemError                    NewHandle errors
  16381. ???                         NewAlias errors
  16382.  
  16383. The NewSection function internally calls the RegisterSection function to inform
  16384. the Edition Manager about a section.
  16385.  
  16386. æKY RegisterSection
  16387. æFc Editions.h
  16388. æT Function
  16389. æTN A82D
  16390. æD pascal OSErr RegisterSection(const CanonicalFileSpec *sectionDocument,SectionHandle sectionH,
  16391.     Boolean *aliasWasChanged)
  16392.     = {0x303C,0x0604,0xA82D}; 
  16393. æDT OSErr myVariable = RegisterSection((const CanonicalFileSpec *) sectionDocument,(SectionHandle) sectionH,(
  16394.     Boolean) * aliasWasChanged);
  16395. æC 
  16396. The sectionDocument parameter is the file name of the document containing the
  16397. section. This parameter cannot be NIL.
  16398.  
  16399. The aliasWasChanged parameter returns TRUE if the alias for the edition
  16400. container subscribed to is out of date. If so, the RegisterSection function
  16401. updates the alias. This may occur if the file is moved to a new location or is
  16402. renamed.
  16403.  
  16404. The RegisterSection function adds the section record to the Edition Manager’s
  16405. list of registered sections, and allocates a control block. After calling the
  16406. RegisterSection function, the control block is either NIL or a valid control
  16407. block. The control block is NIL if the RegisterSection function cannot locate
  16408. the edition container being subscribed to. The RegisterSection function returns
  16409. containerNotFoundWrn. 
  16410.  
  16411. You can compare control blocks for individual sections. If two sections contain
  16412. the same control block value, these sections subscribe to the same edition. The
  16413. Edition Manager needs to be informed when no sections are referencing a control
  16414. block so that it can be deallocated. The control block maintains a count of how
  16415. many sections are referencing it. Each time you use the UnRegisterSection
  16416. function, the control block removes one from the number of sections. When the
  16417. number of sections reaches 0, the control block is deallocated.
  16418.  
  16419. For each section that you cannot register, you should display the document on
  16420. the user’s screen, scroll to the location of the section, and then call the
  16421. FindEditionContainerDialog function.
  16422.  
  16423. Result codes
  16424. noErr                    0  No error
  16425. editionMgrInitErr     -450  Manager not init’ed
  16426. badSectionErr         -451  Not valid SectionType
  16427. multiplePublisherWrn  -460  Already is a publisher
  16428. containerNotFoundWrn  -461  Alias was not resolved
  16429. ???                         MatchAlias errors
  16430.  
  16431. æKY UnRegisterSection
  16432. æFc Editions.h
  16433. æT Function
  16434. æTN A82D
  16435. æD pascal OSErr UnRegisterSection(SectionHandle sectionH)
  16436.     = {0x303C,0x0206,0xA82D}; 
  16437. æDT OSErr myVariable = UnRegisterSection((SectionHandle) sectionH);
  16438. æC 
  16439. When a section needs to be disposed of because the document containing the
  16440. section is closing, or the user is canceling the section, you need to call the
  16441. UnRegisterSection function.
  16442.  
  16443. The sectionH parameter is a handle to the section record for a given section.
  16444.  
  16445. The UnRegisterSection function removes the section from the application’s list
  16446. of registered sections. You can then dispose of the section record and alias
  16447. record with standard memory and resource manager calls. Once unregistered, a
  16448. section does not received any events and cannot read or write any data.
  16449. Depending on your clipboard strategy, you may want to unregister sections that
  16450. have been cut into the clipboard.
  16451.  
  16452. Result codes
  16453. noErr                       0  No error
  16454. editionMgrInitErr        -450  Manager not init’ed
  16455. fBsyErr                        Section doing I/O
  16456. notRegisteredSectionErr  -452  Not registered
  16457.  
  16458. æKY IsRegisterSection
  16459. æFc Editions.h
  16460. æT Function
  16461. æTN A82D
  16462. æD pascal OSErr IsRegisterSection(const SectionHandle sectionH)
  16463.     = {0x303C,0x0208,0xA82D}; 
  16464. æDT OSErr myVariable = IsRegisterSection((const SectionHandle) sectionH);
  16465. æC 
  16466. Each time your application receives a section event, your application must use
  16467. the IsRegisteredSection function to verify that the event received is for a
  16468. registered section.
  16469.  
  16470. The sectionH parameter is a handle to the section record for a given section.
  16471. The IsRegisteredSection function does not return a Boolean—noErr indicates that
  16472. a section is registered.
  16473.  
  16474. Result codes
  16475. noErr                       0  No error
  16476. notRegisteredSectionErr  -452  Not registered
  16477.  
  16478. æKY FindEditionContainerDialog
  16479. æFc Editions.h
  16480. æT Function
  16481. æTN A82D
  16482. æD pascal OSErr FindEditionContainerDialog(const CanonicalFileSpec *sectionDocument,
  16483.     SectionHandle sectionH,Boolean *aliasWasChanged)
  16484.     = {0x303C,0x060A,0xA82D}; 
  16485. æDT OSErr myVariable = FindEditionContainerDialog((const CanonicalFileSpec *) sectionDocument,()
  16486.     SectionHandle sectionH,(Boolean *) aliasWasChanged);
  16487. æC 
  16488. If an edition container cannot be found for a particular section during
  16489. registration, use the FindEditionContainerDialog to resolve the alias record of
  16490. the section.
  16491.  
  16492. The sectionDocument parameter is the file name of the document containing a
  16493. section in canonical form. This parameter cannot be NIL. If the
  16494. FindEditionContainerDialog function is successful, the sectionH parameter
  16495. contains the handle to the allocated section record.
  16496.  
  16497. The aliasWasChanged parameter returns TRUE if the alias for the edition
  16498. container that you are subscribing is out of date. This may occur if the file is
  16499. moved to a new location or is renamed.
  16500.  
  16501. The FindEditionContainerDialog functions assumes that your sections are
  16502. contained within the linked list of registered sections.If the
  16503. FindEditionContainerDialog function cannot locate the edition container, it will
  16504. display a dialog box on the user’s screen.
  16505.  
  16506. Result codes
  16507. noErr                    0  No error
  16508. editionMgrInitErr     -450  Manager not init’ed
  16509. containerNotFoundWrn  -461  Alias was not resolved
  16510. multiplePublisherWrn  -460  Already is a publisher
  16511. ???                         SelectAlias errors
  16512.  
  16513. æKY AssociateSection
  16514. æFc Editions.h
  16515. æT Function
  16516. æTN A82D
  16517. æD pascal OSErr AssociateSection(SectionHandle sectionH,const CanonicalFileSpec *newSectionDocument)
  16518.     = {0x303C,0x040C,0xA82D}; 
  16519. æDT OSErr myVariable = AssociateSection((SectionHandle) sectionH,(const CanonicalFileSpec *) newSectionDocument);
  16520. æC 
  16521. If a user renames a document that contains sections or pastes a portion of a
  16522. document that contains a section into another document, use the AssociateSection
  16523. to update the alias record.
  16524.  
  16525. The sectionH parameter is a handle to the section record for a given section.
  16526. The newSectionDocument contains the volume, folder and file name of the new
  16527. document. The AssociateSection function calls the update alias on the alias
  16528. record.
  16529.  
  16530. Result codes
  16531. noErr         0  No error
  16532. ???              UpdateAlias errors
  16533.  
  16534. æKY CreateEditionContainerFile
  16535. æFc Editions.h
  16536. æT Function
  16537. æTN A82D
  16538. æD pascal OSErr CreateEditionContainerFile(const CanonicalFileSpec *editionFile,
  16539.     OSType fdCreator,Short editionFileNameScript)
  16540.     = {0x303C,0x050E,0xA82D}; 
  16541. æDT OSErr myVariable = CreateEditionContainerFile((const CanonicalFileSpec *) editionFile,()
  16542.     OSType fdCreator,(Short) editionFileNameScript);
  16543. æC 
  16544. Each time a user creates a new publisher section within a document to an edition
  16545. that does not already exist, you use the CreateEditionContainerFile to create an
  16546. empty edition container.
  16547.  
  16548. The containerFile parameter contains the volume, folder and file name for the
  16549. edition container being created. The fdCreator parameter contains the creator
  16550. type for the edition.
  16551.  
  16552. The CreateEditionContainerFile function creates an empty edition container file
  16553. (it does not contain any formats). This function creates a file with type
  16554. 'publ'. If your application has a bundle, you should designate an icon for it
  16555. now.
  16556.  
  16557. Result codes
  16558. noErr                   0  No error
  16559. editionMgrInitErr    -450  Manager not init’ed
  16560. ???                        PBHCreate errors
  16561. ???                        PBHOpen errors
  16562. ???                        PBWrite errors
  16563.  
  16564. æKY DeleteEditionContainerFile
  16565. æFc Editions.h
  16566. æT Function
  16567. æTN A82D
  16568. æD pascal OSErr DeleteEditionContainerFile(const CanonicalFileSpec *editionFile)
  16569.     = {0x303C,0x0210,0xA82D}; 
  16570. æDT OSErr myVariable = DeleteEditionContainerFile((const CanonicalFileSpec *) editionFile);
  16571. æC 
  16572. If a user cancels a publisher section within a document or closes a document
  16573. containing a newly created publisher without saving, you need to remove the
  16574. edition container using the DeleteEditionContainerFile function.
  16575.  
  16576. The containerFile parameter contains the volume, folder and file name for the
  16577. edition container being deleted.
  16578.  
  16579. You should use the DeleteEditionContainerFile function even if there are
  16580. subscribers to the edition. When a subscriber section tries to read in data, it
  16581. receives an error.
  16582.  
  16583. Result codes
  16584. noErr                   0  No error
  16585. editionMgrInitErr    -450  Manager not init’ed
  16586. ???                        PBHDelete errors
  16587.  
  16588. æKY OpenEdition
  16589. æFc Editions.h
  16590. æT Function
  16591. æTN A82D
  16592. æD pascal OSErr OpenEdition(SectionHandle subscriberSectionH,EditionRefNum *refNum)
  16593.     = {0x303C,0x0412,0xA82D}; 
  16594. æDT OSErr myVariable = OpenEdition((SectionHandle) subscriberSectionH,(EditionRefNum *) refNum);
  16595. æC 
  16596. You initiate the reading of data from an edition (for a subscriber), use the
  16597. OpenEdition function.
  16598.  
  16599. The subscriberSectionH parameter is a handle to the section record for a given
  16600. section. The refnum parameter returns the reference number for the edition.
  16601.  
  16602. Multiple subscribers can simultaneously read data from a single edition.
  16603.  
  16604. Result codes
  16605. noErr                   0  No error
  16606. editionMgrInitErr    -450  Manager not init’ed
  16607. permErr                    Not a subscriber
  16608.  
  16609. æKY OpenNewEdition
  16610. æFc Editions.h
  16611. æT Function
  16612. æTN A82D
  16613. æD pascal OSErr OpenNewEdition(SectionHandle publisherSectionH,OSType fdCreator,
  16614.     const CanonicalFileSpec *publisherSectionDocument,EditionRefNum *refNum)
  16615.     = {0x303C,0x0814,0xA82D}; 
  16616. æDT OSErr myVariable = OpenNewEdition((SectionHandle) publisherSectionH,(OSType) fdCreator,(
  16617.     const CanonicalFileSpec) * publisherSectionDocument,(EditionRefNum *) refNum);
  16618. æC 
  16619. To initiate the writing of data from a publisher to its edition container, use
  16620. the OpenNewEdition function.
  16621.  
  16622. The publisherSectionH parameter is the publisher section that you are writing to
  16623. the edition. The fdCreator parameter is the Finder creator type of the new
  16624. edition icon.
  16625.  
  16626. The sectionDocument parameter is the document which contains the publisher. This
  16627. parameter is used to create an alias from the edition to the document containing
  16628. the publisher. If you pass NIL for sectionDocument, an alias is not made and the
  16629. GotoPublisherSection function is unable to open the document containing the
  16630. publisher.
  16631.  
  16632. The refnum parameter returns the reference number for the edition. This
  16633. parameter is necessary for subsequent calls to WriteEdition,
  16634. SetEditionFormatMark, and CloseEdition to specify which publisher is writing its
  16635. data to an edition. If the edition cannot be opened for writing because there is
  16636. another publisher writing to it, or because the file system does not allow
  16637. writing, an error is returned and refNum is set to NIL.
  16638.  
  16639. Result codes
  16640. noErr                   0  No error
  16641. editionMgrInitErr    -450  Manager not init’ed
  16642. wrPermErr                  Not a publisher
  16643. notThePublisherWrn   -462  Not the publisher
  16644. ???                        NewHandle errors
  16645. ???                        PBHCreate errors
  16646. ???                        PBHOpen errors
  16647. ???                        NewAlias errors
  16648.  
  16649. æKY CloseEdition
  16650. æFc Editions.h
  16651. æT Function
  16652. æTN A82D
  16653. æD pascal OSErr CloseEdition(EditionRefNum whichEdition,Boolean success)
  16654.     = {0x303C,0x0316,0xA82D}; 
  16655. æDT OSErr myVariable = CloseEdition((EditionRefNum) whichEdition,(Boolean) success);
  16656. æC 
  16657. After finishing reading from or writing to an edition, use the CloseEdition
  16658. function to close the edition.
  16659.  
  16660. The refnum parameter is the reference number for edition. Set the success
  16661. parameter is set to TRUE if the edition successfully closes. If not, set this
  16662. parameter to FALSE.
  16663.  
  16664. When you are finished reading data from an edition and you are using the
  16665. CloseEdition function, the EditionRefNum value becomes invalid. If the success
  16666. parameter is set to TRUE, the CloseEdition function takes the modification date
  16667. of the edition file that you have read in and puts it in the mdDate field of the
  16668. subscriber’s section record. This indicates that the data contained in the
  16669. edition and the subscriber section within the document are the same.
  16670.  
  16671. If you set the success parameter to FALSE because you are unable to read the
  16672. edition data (if there is not enough memory, or you didn’t find a format that
  16673. you can read), the CloseEdition function closes the edition, but does not set
  16674. the modification date field. This implies that the subscriber is not updated
  16675. with the latest edition.
  16676.  
  16677. When you have successfully finished writing data to an edition and you are using
  16678. the CloseEdition function, you should set the success parameter to TRUE. When
  16679. you do so, the data that you have written to the edition becomes available to
  16680. any subscribers. The Edition Manager sends a SectionReadEvent to all current
  16681. subscribers. The CloseEdition function sets the modification date (mdDate) of
  16682. the edition to correspond to the modification date of the publisher’s section
  16683. record. Each time a user edits a publisher within a document, you need to update
  16684. the modification date (even if the data is not yet written). 
  16685.  
  16686. If you set the success parameter to FALSE because you are unable to successfully
  16687. write data to the edition, the Edition Manager does not write any data to the
  16688. edition. The data contained in the edition prior to writing is restored.
  16689. SectionReadEvents are not sent to subscribers.
  16690.  
  16691. Result codes
  16692. noErr                   0  No error
  16693. editionMgrInitErr    -450  Manager not init’ed
  16694. rfNumErr                   Bad refNum
  16695. ???                        PBWrite errors
  16696. ???                        DisposHandle errors
  16697.  
  16698. æKY EditionHasFormat
  16699. æFc Editions.h
  16700. æT Function
  16701. æTN A82D
  16702. æD pascal OSErr EditionHasFormat(EditionRefNum whichEdition,FormatType whichFormat,
  16703.     Size *length)
  16704.     = {0x303C,0x0618,0xA82D}; 
  16705. æDT OSErr myVariable = EditionHasFormat((EditionRefNum) whichEdition,(FormatType) whichFormat,(
  16706.     Size) * length);
  16707. æC 
  16708. Use the EditionHasFormat function to find out in which formats the edition data
  16709. is available.
  16710.  
  16711. The whichEdition parameter is the reference number for the edition. The
  16712. whichFormat parameter indicates the format type that you are requesting. Apple
  16713. Computer recommends that you request formats in order of preference.
  16714.  
  16715. Upon return of the EditionHasFormat function, the length parameter contains the
  16716. length of the format for the edition you are specifying. If the requested format
  16717. is available, this function returns noErr and the length field returns the size
  16718. of the data in the specified format or kFormatLengthUnknown (-1) which signifies
  16719. that the size is unknown. You should continue to read the format until there is
  16720. no more data.
  16721.  
  16722. Be aware that the EditionHasFormat function may return kFormatLengthUnknown for
  16723. the length of the format.
  16724.  
  16725. Result codes
  16726. noErr                   0  No error
  16727. noTypeErr                  Format not available
  16728. editionMgrInitErr    -450  Manager not init’ed
  16729.  
  16730. æKY ReadEdition
  16731. æFc Editions.h
  16732. æT Function
  16733. æTN A82D
  16734. æD pascal OSErr ReadEdition(EditionRefNum whichEdition,FormatType whichFormat,
  16735.     Ptr buffPtr,Size *buffLen)
  16736.     = {0x303C,0x081A,0xA82D}; 
  16737. æDT OSErr myVariable = ReadEdition((EditionRefNum) whichEdition,(FormatType) whichFormat,()
  16738.     Ptr buffPtr,(Size *) buffLen);
  16739. æC 
  16740. Use the ReadEdition function to read data from an edition.
  16741.  
  16742. The whichEdition parameter is the reference number for the edition. The
  16743. whichFormat parameter indicates the format type that you want to read. 
  16744. The buffPtr parameter is a pointer to the buffer into which you are reading the
  16745. edition from. The buffLen parameter is the number of bytes that you want to read
  16746. into the buffer. The buffLen parameter is also a return value that returns the
  16747. total number of bytes read into the buffer. Once the buffLen field returns a
  16748. value less than the value you have specified, there is no additional data to
  16749. read, and the ReadEdition function returns noErr. If use the ReadEdition
  16750. function after all data is read in, the ReadEdition function returns an EoFErr.
  16751.  
  16752. Result codes
  16753. noErr                   0  No error
  16754. editionMgrInitErr    -450  Manager not init’ed
  16755. noTypeErr                  Format not available
  16756. rfNumErr                   Bad refNum
  16757. EofErr
  16758.  
  16759. æKY WriteEdition
  16760. æFc Editions.h
  16761. æT Function
  16762. æTN A82D
  16763. æD pascal OSErr WriteEdition(EditionRefNum whichEdition,FormatType whichFormat,
  16764.     Ptr buffPtr,Size buffLen)
  16765.     = {0x303C,0x081C,0xA82D}; 
  16766. æDT OSErr myVariable = WriteEdition((EditionRefNum) whichEdition,(FormatType) whichFormat,()
  16767.     Ptr buffPtr,(Size) buffLen);
  16768. æC 
  16769. Use the WriteEdition function to write data to an edition.
  16770.  
  16771. The refnum parameter is the reference number for edition. The whichFormat
  16772. parameter indicates the format type that you want to write. 
  16773.  
  16774. The buffPtr parameter is a pointer to the buffer that you are writing into the
  16775. edition. The buffLen parameter is the number of bytes that you are writing. If
  16776. data cannot be entirely written to the edition, the WriteEdition function
  16777. returns a error.
  16778.  
  16779. Result codes
  16780. noErr                   0  No error
  16781. editionMgrInitErr    -450  Manager not init’ed
  16782. noTypeErr                  Unknown format
  16783. rfNumErr                   Bad refNum
  16784.  
  16785. æKY GetEditionFormatMark
  16786. æFc Editions.h
  16787. æT Function
  16788. æTN A82D
  16789. æD pascal OSErr GetEditionFormatMark(EditionRefNum whichEdition,FormatType whichFormat,
  16790.     long *currentMark)
  16791.     = {0x303C,0x061E,0xA82D}; 
  16792. æDT OSErr myVariable = GetEditionFormatMark((EditionRefNum) whichEdition,(FormatType) whichFormat,(
  16793.     long) * currentMark);
  16794. æC 
  16795. Use the GetEditionFormatMark to locate the current marker for a particular
  16796. format.
  16797.  
  16798. The whichEdition parameter is the reference number for the edition. The
  16799. whichFormat parameter indicates the format type for the edition and the
  16800. currentMark parameter is the offset for the format. 
  16801.  
  16802. If you do not support the format that you are specifying, you receive noTypeErr.
  16803.  
  16804. Result codes
  16805. noErr         0  No error
  16806. noTypeErr        Unknown format
  16807. posErr           Mark not set anywhere
  16808.  
  16809. æKY SetEditionFormatMark
  16810. æFc Editions.h
  16811. æT Function
  16812. æTN A82D
  16813. æD pascal OSErr SetEditionFormatMark(EditionRefNum whichEdition,FormatType whichFormat,
  16814.     long setMarkTo)
  16815.     = {0x303C,0x0620,0xA82D}; 
  16816. æDT OSErr myVariable = SetEditionFormatMark((EditionRefNum) whichEdition,(FormatType) whichFormat,()
  16817.     long setMarkTo);
  16818. æC 
  16819. Use the SetEditionFormatMark to set the current mark for a section format.
  16820.  
  16821. The whichEdition parameter is the reference number for the edition. The
  16822. whichFormat parameter indicates the format type for the edition and the
  16823. setMarkTo parameter is the offset for the format.
  16824.  
  16825. When you are creating a publisher, and if the whichFormat does not exist for a
  16826. particular edition that you are writing data to, the SetEditionFormatMark
  16827. creates the format. You need to call the SetEditionFormatMark function before
  16828. writing data.
  16829.  
  16830. Result codes
  16831. noErr         0  No error
  16832. posErr           Manager not init’ed
  16833. ???              SetHandleSize errors
  16834.  
  16835. æKY GetEditionInfo
  16836. æFc Editions.h
  16837. æT Function
  16838. æTN A82D
  16839. æD pascal OSErr GetEditionInfo(const SectionHandle sectionH,EditionInfoRecord *editionInfo)
  16840.     = {0x303C,0x0422,0xA82D}; 
  16841. æDT OSErr myVariable = GetEditionInfo((const SectionHandle) sectionH,(EditionInfoRecord *) editionInfo);
  16842. æC 
  16843. When the user wants to locate the publisher for a particular subscriber (by
  16844. choosing Find Publisher in the subscriber options dialog box), use the
  16845. GetEditionInfo function to find the edition container. You should then call the
  16846. GotoPublisherSection function.
  16847.  
  16848. The GetEditionInfo function returns information about a section’s edition such
  16849. as it’s location, last modification date, creator and type. This function only
  16850. works for registered sections which contain a non-NIL control block.
  16851.  
  16852. The sectionH parameter is a handle to the section record for a given section.
  16853. The editionInfo parameter is a pointer from the EditionInfo record. The
  16854. GetEditionInfo function comprises the public information contained in the
  16855. control block.
  16856.  
  16857. The Edition Manager syncs to ensure that the existing edition name corresponds
  16858. to the Finder’s existing edition name. Refer to “Reading and Writing Edition
  16859. Data” for additional information. If an edition container could not be located
  16860. previously, the GetEditionInfo function tries to locate it again. If it cannot
  16861. be located a second time, the GetEditionInfo function returns a file not found
  16862. err.
  16863.  
  16864. TYPE EditionInfoRecord = 
  16865. RECORD
  16866.   crDate:     TimeStamp;
  16867.   mdDate:     TimeStamp;
  16868.   fdCreator:  OSType;
  16869.   fdType:     OSType;
  16870.   container:  EditionContainerSpec;
  16871. END;
  16872.  
  16873. The fdType field is the creator type 'publ'. The fdCreator field is specified in
  16874. the OpenNewEdition function. The container field is a volume, folder, and file
  16875. name for the edition.
  16876.  
  16877. The crDate field contains the creation date of the edition. The mdDate field
  16878. contains the modification date of the edition.
  16879.  
  16880. Result codes
  16881. noErr                   0  No error
  16882. editionMgrInitErr    -450  Manager not init’ed
  16883. fnfErr                     Not registered or file moved
  16884. ???                        PBHGetFInfo
  16885.  
  16886. æKY GotoPublisherSection
  16887. æFc Editions.h
  16888. æT Function
  16889. æTN A82D
  16890. æD pascal OSErr GotoPublisherSection(const EditionContainerSpec *container)
  16891.     = {0x303C,0x0224,0xA82D}; 
  16892. æDT OSErr myVariable = GotoPublisherSection((const EditionContainerSpec *) container);
  16893. æC 
  16894. Use the GotoPublisherSection function to resolve the alias in the edition to
  16895. find the document containing its publisher. This function opens the document,
  16896. launches it’s application if necessary, and scrolls to the location of the
  16897. publisher. 
  16898.  
  16899. The container parameter is the edition volume, folder, and file name. You obtain
  16900. the container by calling the GetEditionInfo function.
  16901.  
  16902. You should call the GotoPublisherSection function when the user selects Find
  16903. Publisher within the publisher options dialog box. The action code 'goto' is
  16904. returned to you.
  16905.  
  16906. Result codes
  16907. noErr                   0  No error
  16908. editionMgrInitErr    -450  Manager not init’ed
  16909. badSubPartErr        -454  Invalid container
  16910. MemError                   NewHandle errors
  16911. ???                        ResolveAlias errors
  16912.  
  16913. æKY GetLastEditionContainerUsed
  16914. æFc Editions.h
  16915. æT Function
  16916. æTN A82D
  16917. æD pascal OSErr GetLastEditionContainerUsed(const EditionContainerSpec *container)
  16918.     = {0x303C,0x0226,0xA82D}; 
  16919. æDT OSErr myVariable = GetLastEditionContainerUsed((const EditionContainerSpec *) container);
  16920. æC 
  16921. The Edition Manager supports three dialog boxes: new publisher and new
  16922. subscriber dialog boxes and an options dialog box. Your application can display
  16923. “simple” dialog boxes which require reply records, or you can customize your
  16924. dialog boxes.
  16925.  
  16926. Use the GetLastEditionContainerUsed function to display the last edition within
  16927. the dialog boxes. This function enables a user to easily subscribe to the data
  16928. recently published.
  16929.  
  16930. If the GetLastEditionContainer function locates the last edition for which a
  16931. section was created, the container parameter contains its volume, folder, file
  16932. name, part, and returns noErr. (The last edition created is associated with the
  16933. last time that you used the NewSection function.) If the last edition created to
  16934. is moved or deleted, the GetLastEditionContainer function cannot locate the last
  16935. edition. The container parameter returns the volume and folder for the edition,
  16936. leaves the file name blank, and returns fnfErr.
  16937.  
  16938. The Edition Manager syncs to ensure that its existing edition name corresponds
  16939. to the Finder’s existing edition name. Refer to “Reading and Writing Edition
  16940. Data” for additional information.
  16941.  
  16942. Pass the information from the GetLastEditionContainerUsed function to the
  16943. NewSubscriberDialog and the NewPublisherDialog functions.
  16944.  
  16945. Result codes
  16946. noErr                   0  No error
  16947. editionMgrInitErr    -450  Manager not init’ed
  16948. fnfErr                     Container not found
  16949.  
  16950. æKY GetStandardFormats
  16951. æFc Editions.h
  16952. æT Function
  16953. æTN A82D
  16954. æD pascal OSErr GetStandardFormats(const EditionContainerSpec *container,FormatType *previewFormat,
  16955.     Handle preview,Handle publisherAliss,Handle formats)
  16956.     = {0x303C,0x0A28,0xA82D}; 
  16957. æDT OSErr myVariable = GetStandardFormats((const EditionContainerSpec *) container,(FormatType *) previewFormat,()
  16958.     Handle preview,(Handle) publisherAliss,(Handle) formats);
  16959. æC 
  16960. This function is called by the Edition Manager to get the alias used in the
  16961. GotoPublisherSection function and to get the preview shown in the new subscriber
  16962. dialog box. You will probably not need to call this function directly.
  16963.  
  16964. The container parameter is a pointer to the edition volume, folder, file name
  16965. and part.
  16966.  
  16967. You should pass in valid handes for the formats that you want and NIL for the
  16968. formats that you don’t want. The handles are resized to the size of the data.
  16969. The handle fmts reads the virtual format kFormatListFormat, the handle alis
  16970. reads the format kPublisherDocAliasFormat and the handle prvw tries to find the
  16971. following formats in this order: prvw, PICT and then TEXT. The first format
  16972. located returns in the preview handle and the previewFormat parameter is set to
  16973. its type. If none of the requested formats can be found, noTypeErr is returned.
  16974.  
  16975. Result codes
  16976. noErr                   0  No error
  16977. editionMgrInitErr    -450  Manager not init’ed
  16978. noTypeErr                  Container not found
  16979. MemError                   SetHandleSize errors
  16980. ???                        ResolveAlias errors
  16981.  
  16982. æKY GetEditionOpenerProc
  16983. æFc Editions.h
  16984. æT Function
  16985. æTN A82D
  16986. æD pascal OSErr GetEditionOpenerProc(EditionOpenerProcPtr *opener)
  16987.     = {0x303C,0x022A,0xA82D}; 
  16988. æDT OSErr myVariable = GetEditionOpenerProc((EditionOpenerProcPtr *) opener);
  16989. æC 
  16990. Use the GetEditionOpenerProc to locate the current edition opener procedure.
  16991.  
  16992. The opener procedure returns the pointer to the current edition opener
  16993. procedure.
  16994.  
  16995. The PB parameter of the CallFormatIOProc function is a FormatIOParamBlock
  16996. record.
  16997.  
  16998. TYPE FormatIOParamBlock = 
  16999. RECORD
  17000.   ioRefNum:     LongInt;     {}
  17001.   format:       FormatType;  {}
  17002.   formatIndex:  LongInt;     {}
  17003.   offset:       LongInt;     {}
  17004.   buffPtr:      Ptr;         {}
  17005.   buffLen:      LongInt;     {}
  17006. END;
  17007.  
  17008. The routine parameter is a pointer to a format I/O procedure.
  17009.  
  17010. You should have an IO function that contains the following parameters.
  17011.  
  17012. FUNCTION IO (selector: FormatIOVerb; VAR PB: FormatIOParamBlock) : OSErr;
  17013.  
  17014. æKY SetEditionOpenerProc
  17015. æFc Editions.h
  17016. æT Function
  17017. æTN A82D
  17018. æD pascal OSErr SetEditionOpenerProc(EditionOpenerProcPtr opener)
  17019.     = {0x303C,0x022C,0xA82D}; 
  17020. æDT OSErr myVariable = SetEditionOpenerProc((EditionOpenerProcPtr) opener);
  17021. æC 
  17022. Use the SetEditionOpenProc to provide your own edition opener procedure.
  17023.  
  17024. The opener parameter is a pointer to the edition opener procedure that you are
  17025. providing.
  17026.  
  17027.  
  17028. æKY CallEditionOpenerProc
  17029. æFc Editions.h
  17030. æT Function
  17031. æTN A82D
  17032. æD pascal OSErr CallEditionOpenerProc(EditionOpenerVerb selector,EditionOpenerParamBlock *PB,
  17033.     EditionOpenerProcPtr routine)
  17034.     = {0x303C,0x052E,0xA82D}; 
  17035. æDT OSErr myVariable = CallEditionOpenerProc((EditionOpenerVerb) selector,(EditionOpenerParamBlock *) PB,()
  17036.     EditionOpenerProcPtr routine);
  17037. æC 
  17038. The Edition Manager never opens or closes an edition container directly—it calls
  17039. the current “EditionOpener.” Use the CallEditionOpenerProc to call the edition
  17040. opener procedure pointer.
  17041.  
  17042. Set the selector parameter to one of the edition opener verbs (eoOpen, eoClose,
  17043. eoOpenNew, eoCloseNew, eoCanSubscribe). The params parameter is an
  17044. EditionOpenerParamBlock record.
  17045.  
  17046. TYPE EditionOpenerParamBlock = 
  17047. RECORD
  17048.   info:      EditionInfoRecord;      {}
  17049.   sectionH:  SectionHandle;          {}
  17050.   document:  CanonicalFileSpecPtr;   {}
  17051.   misc:      LongInt;                {}
  17052.   ioRefNum:  LongInt;                {}
  17053.   ioProc:    FormatIOProcPtr;        {}
  17054. END;
  17055.  
  17056. The routine parameter is a pointer to an edition opener procedure.
  17057.  
  17058. æKY CallFormatIOProc
  17059. æFc Editions.h
  17060. æT Function
  17061. æTN A82D
  17062. æD pascal OSErr CallFormatIOProc(FormatIOVerb selector,FormatIOParamBlock *PB,
  17063.     FormatIOProcPtr routine)
  17064.     = {0x303C,0x0530,0xA82D}; 
  17065. æDT OSErr myVariable = CallFormatIOProc((FormatIOVerb) selector,(FormatIOParamBlock *) PB,()
  17066.     FormatIOProcPtr routine);
  17067. æC 
  17068.  
  17069. æKY NewSubscriberDialog
  17070. æFc Editions.h
  17071. æT Function
  17072. æTN A82D
  17073. æD pascal OSErr NewSubscriberDialog(NewSubscriberReply *reply)
  17074.     = {0x303C,0x0232,0xA82D}; 
  17075. æDT OSErr myVariable = NewSubscriberDialog((NewSubscriberReply *) reply);
  17076. æC 
  17077. Use the NewSubscriberDialog function to display the new subscriber dialog box on
  17078. the user’s screen.
  17079.  
  17080. FUNCTION NewSubscriberDialog (VAR reply: NewSubscriberReply) : OSErr;
  17081.  
  17082. The reply parameter is the NewSubscriberReply record.
  17083.  
  17084. TYPE NewSubscriberReply = 
  17085. RECORD
  17086.   canceled:   Boolean;               {out}
  17087.   container:  EditionContainerSpec;  {in/out}
  17088. END;
  17089.  
  17090. Set the container parameter to be a pointer to a volume, folder, file name, and
  17091. part for the last edition subscribed to.
  17092.  
  17093. Upon return of the NewSubscriberDialog function, if the canceled parameter is
  17094. set to TRUE, the user canceled the dialog box. Otherwise, this parameter is
  17095. FALSE and the container parameter holds the container for the new subscriber.
  17096.  
  17097. Result codes
  17098. noErr                   0  No error
  17099. editionMgrInitErr    -450  Package not init’ed
  17100. badSubPartErr        -454  Bad container spec
  17101. MemError                   NewHandle errors
  17102. ResError                   GetResource errors
  17103.  
  17104. æKY NewSubscriberExpDialog
  17105. æFc Editions.h
  17106. æT Function
  17107. æTN A82D
  17108. æD pascal OSErr NewSubscriberExpDialog(NewSubscriberReply *reply,Point where,
  17109.     Short expansionDITLresID,ExpDlgHookProcPtr dlgHook,ExpModalFilterProcPtr filterProc,
  17110.     Ptr yourDataPtr)
  17111.     = {0x303C,0x0B34,0xA82D}; 
  17112. æDT OSErr myVariable = NewSubscriberExpDialog((NewSubscriberReply *) reply,(Point) where,()
  17113.     Short expansionDITLresID,(ExpDlgHookProcPtr) dlgHook,(ExpModalFilterProcPtr) filterProc,()
  17114.     Ptr yourDataPtr);
  17115. æC 
  17116. Use the NewSubscriberExpDialog function to customize the new subscriber dialog
  17117. box.
  17118.  
  17119. The NewSubscriberExpDialog, NewPublisherExpDialog, and SectionOptionsExpDialog
  17120. functions share the same parameters. Refer below for a detailed explanation of
  17121. the parameters.
  17122.  
  17123. Result codes
  17124. noErr                   0  No error
  17125. editionMgrInitErr    -450  Package not init’ed
  17126. MemError                   NewHandle errors
  17127. ResError                   GetResource errors
  17128.  
  17129. æKY NewPublisherDialog
  17130. æFc Editions.h
  17131. æT Function
  17132. æTN A82D
  17133. æD pascal OSErr NewPublisherDialog(NewSubscriberReply *reply)
  17134.     = {0x303C,0x0236,0xA82D}; 
  17135. æDT OSErr myVariable = NewPublisherDialog((NewSubscriberReply *) reply);
  17136. æC 
  17137. Use the NewPublisherDialog function to display the new publisher dialog box on
  17138. the user’s screen.
  17139.  
  17140. The reply parameter is a pointer from the NewPublisherReply record.
  17141.  
  17142. TYPE NewPublisherReply = 
  17143. RECORD
  17144.   canceled:       Boolean;              {out}
  17145.   replacing:      Boolean;              {out}
  17146.   usePart:        Boolean;              {in}
  17147.   preview:        Handle;               {in}
  17148.   previewFormat:  FormatType;           {in}
  17149.   container:      EditionContainerSpec  {in/out}
  17150. END;
  17151.  
  17152. The usePart parameter must be set to FALSE before calling the NewPublisherDialog
  17153. routine.
  17154.  
  17155. Set the container parameter to be a pointer to a volume, folder, and file name
  17156. for a default edition. Set the preview parameter to be a handle to the format
  17157. for the default edition and set the previewFormat parameter to indicate the
  17158. format of the default edition.
  17159.  
  17160. Upon return of the NewPublisherDialog function, the following three output
  17161. parameters can be set. If the canceled parameter is set to TRUE, the user
  17162. canceled the dialog box. If the replacing parameter is TRUE, the user chose an
  17163. existing file name from the list of available editions and confirmed this
  17164. replacement. If the replacing parameter is TRUE, do not call the
  17165. CreateEditionContainerFile function which creates a new edition container. The
  17166. container parameter contains the volume, folder and file name for the default
  17167. edition. 
  17168. Deallocate the preview parameter to free up memory.
  17169.  
  17170. Result codes
  17171. noErr                   0  No error
  17172. editionMgrInitErr    -450  Package not init’ed
  17173. badSubPartErr        -454  Bad container spec
  17174. MemError                   NewHandle errors
  17175. ResError                   GetResource errors
  17176.  
  17177. æKY NewPublisherExpDialog
  17178. æFc Editions.h
  17179. æT Function
  17180. æTN A82D
  17181. æD pascal OSErr NewPublisherExpDialog(NewSubscriberReply *reply,Point where,
  17182.     Short expansionDITLresID,ExpDlgHookProcPtr dlgHook,ExpModalFilterProcPtr filterProc,
  17183.     Ptr yourDataPtr)
  17184.     = {0x303C,0x0B38,0xA82D}; 
  17185. æDT OSErr myVariable = NewPublisherExpDialog((NewSubscriberReply *) reply,(Point) where,()
  17186.     Short expansionDITLresID,(ExpDlgHookProcPtr) dlgHook,(ExpModalFilterProcPtr) filterProc,()
  17187.     Ptr yourDataPtr);
  17188. æC 
  17189. Use the NewPublisherExpDialog function to customize the new publisher dialog
  17190. box.
  17191.  
  17192. The NewSubscriberExpDialog, NewPublisherExpDialog, and SectionOptionsExpDialog
  17193. functions share the same parameters. Refer below for a detailed explanation of
  17194. the parameters.
  17195.  
  17196. Result codes
  17197. noErr                   0  No error
  17198. editionMgrInitErr    -450  Package not init’ed
  17199. MemError                   NewHandle errors
  17200. ResError                   GetResource errors
  17201.  
  17202. æKY SectionOptionsDialog
  17203. æFc Editions.h
  17204. æT Function
  17205. æTN A82D
  17206. æD pascal OSErr SectionOptionsDialog(SectionOptionsReply *reply)
  17207.     = {0x303C,0x023A,0xA82D}; 
  17208. æDT OSErr myVariable = SectionOptionsDialog((SectionOptionsReply *) reply);
  17209. æC 
  17210. Use the SectionOptionsDialog function to display the publisher options and
  17211. subscriber options dialog boxes on the user’s screen.
  17212.  
  17213. The reply parameter is a pointer from the SectionOptionsReply record.
  17214.  
  17215. TYPE SectionOptionsReply = 
  17216. RECORD
  17217.   canceled:  Boolean;       {out}
  17218.   changed:   Boolean;       {out}
  17219.   sectionH:  SectionHandle; {in}
  17220.   action:    ResType;       {out}
  17221. END;
  17222.  
  17223. The sectionH parameter is a handle to the section record for a given section.
  17224.  
  17225. Upon return of the SectionOptionsDialog function, the following output
  17226. parameters can be set. If the canceled parameter is set to TRUE, the user
  17227. canceled the dialog box. Otherwise, this parameter is FALSE. If the changed
  17228. parameter is TRUE (if for example, the update mode is changed), the user changed
  17229. the section record.
  17230.  
  17231. The action parameter contains the code for 1 of 4 user actions. 
  17232.  
  17233.   •   action code is 'read' for user selection of Get Edition Now
  17234.   •   action code is 'writ' for user selection of Publish Now
  17235.   •   action code is 'goto' for user selection of Find Publisher
  17236.   •   action code is 'cncl' for user selection of Cancel Publisher or Cancel 
  17237.       Subscriber
  17238.  
  17239. Your application can expand dialog boxes to include DITL items, apply alternate
  17240. mapping of events to item hits, and apply alternate meanings to the item hits.
  17241.  
  17242. æKY SectionOptionsExpDialog
  17243. æFc Editions.h
  17244. æT Function
  17245. æTN A82D
  17246. æD pascal OSErr SectionOptionsExpDialog(SectionOptionsReply *reply,Point where,
  17247.     Short expansionDITLresID,ExpDlgHookProcPtr dlgHook,ExpModalFilterProcPtr filterProc,
  17248.     Ptr yourDataPtr)
  17249.     = {0x303C,0x0B3C,0xA82D}; 
  17250. æDT OSErr myVariable = SectionOptionsExpDialog((SectionOptionsReply *) reply,(Point) where,()
  17251.     Short expansionDITLresID,(ExpDlgHookProcPtr) dlgHook,(ExpModalFilterProcPtr) filterProc,()
  17252.     Ptr yourDataPtr);
  17253. æC 
  17254. Use the SectionOptionsExpDialog function to customize the publisher and
  17255. subscriber dialog boxes.
  17256.  
  17257. The NewSubscriberExpDialog, NewPublisherExpDialog, and SectionOptionsExpDialog
  17258. functions share the same parameters. Refer below for a detailed explanation of
  17259. the parameters.
  17260.  
  17261. Result codes
  17262. noErr                   0  No error
  17263. editionMgrInitErr    -450  Package not init’ed
  17264. MemError                   NewHandle errors
  17265. ResError                   GetResource errors
  17266.  
  17267. The reply parameter is a pointer from the NewSubscriberReply, NewPublisherReply,
  17268. or the SectionOptionsReply records.
  17269.  
  17270. You can automatically center the dialog box by passing <-1, -1> in the where
  17271. field. The expansionDITLresID field should be zero or a valid dialog item list 
  17272. (DITL) resource ID. This integer is the ID of a DITL whose items are appended to
  17273. the end of the standard dialog DITL. The DITL items keep their relative
  17274. positions, but when they are moved, they move as a group to the bottom of the
  17275. dialog box. For international purposes, the location of the DITL items is not
  17276. always the bottom of the dialog box. The location can be specified by a user
  17277. item in the main DITL. For different script systems, you should arrange your
  17278. expansionDITL items appropriately. Refer to the Dialog Manager chapter for
  17279. additional information on DITL.
  17280.  
  17281. The filterProc parameter should be a valid ExpModalFilterProcPtr or NIL. This
  17282. procedure is called by the dialog box filterProc. This function enables you to
  17283. map real events (mouse-down or up or key-down or up) to a hit on an item (such
  17284. as a cancel button). Each item corresponds to a number. You may want to map a
  17285. command-key equivalent to an item hit .
  17286.  
  17287. The dlgHook parameter should be a valid ExpDlgHookProcPtr or NIL. This procedure
  17288. is called with each call to a dialog box. The dlgHook parameter makes the
  17289. appropriate action such as filling in a check box with an ‘X’ if this particular
  17290. item is selected by the user. The itemOffset passed to the procedure is the
  17291. number of items in the dialog item list befoe the expansionDITL items. You need
  17292. to subtract itemOffset from item to get the relative item number in the
  17293. expanstionDITL. The return value from dlgHook is the absolute item number. Some
  17294. special values for item are: kFirstHookCall (-1), kNullHookCall (100), and
  17295. kRebuildFileList (101).
  17296.  
  17297. The callBackPtr parameter is reserved for your use.
  17298.  
  17299.  
  17300. æKY EPPC.h
  17301. æKL AcceptHighLevelEvent
  17302. GetPortNameFromProcessSerialNumber
  17303. GetProcessSerialNumberFromPortName
  17304. GetSpecificHighLevelEvent
  17305. PostHighLevelEvent
  17306.  
  17307. bufferIsSmall
  17308. connectionInValid
  17309. GetSpecificFilterProcPtr
  17310. HighLevelEventMsg
  17311. HighLevelEventMsgClass
  17312. HighLevelEventMsgHdl
  17313. HighLevelEventMsgPtr
  17314. kHighLevelEvent
  17315. msgWasFullyAccepted
  17316. msgWasNotAccepted
  17317. msgWasPartiallyAccepted
  17318. nAttnMsg
  17319. noOutstandingHLE
  17320. nReturnReceipt
  17321. priorityMask
  17322. receiverIDisPSN
  17323. receiverIDisSessionID
  17324. receiverIDisSignature
  17325. receiverIDisTargetID
  17326. receiverIDMask
  17327. registerOnNetwork
  17328. rtrnReciptMsgID
  17329. systemOptionsMask
  17330. TargetID
  17331. TargetIDPtr
  17332.  
  17333. æKY kHighLevelEvent
  17334. æFc EPPC.h
  17335. æT #define
  17336. æD #define kHighLevelEvent 23
  17337. æC 
  17338.  
  17339. æKY receiverIDMask
  17340. æFc EPPC.h
  17341. æT #define
  17342. æD 
  17343. /*  postOptions currently supported */
  17344.  
  17345. #define receiverIDMask 0x0000F000
  17346. æC 
  17347.  
  17348. æKY receiverIDisPSN
  17349. æFc EPPC.h
  17350. æT #define
  17351. æD #define receiverIDisPSN 0x00008000
  17352. æC 
  17353.  
  17354. æKY receiverIDisSignature
  17355. æFc EPPC.h
  17356. æT #define
  17357. æD #define receiverIDisSignature 0x00007000
  17358. æC 
  17359.  
  17360. æKY receiverIDisSessionID
  17361. æFc EPPC.h
  17362. æT #define
  17363. æD #define receiverIDisSessionID 0x00006000
  17364. æC 
  17365.  
  17366. æKY receiverIDisTargetID
  17367. æFc EPPC.h
  17368. æT #define
  17369. æD #define receiverIDisTargetID 0x00005000
  17370. æC 
  17371.  
  17372. æKY systemOptionsMask
  17373. æFc EPPC.h
  17374. æT #define
  17375. æD #define systemOptionsMask 0x00000F00
  17376. æC 
  17377.  
  17378. æKY nReturnReceipt
  17379. æFc EPPC.h
  17380. æT #define
  17381. æD #define nReturnReceipt 0x00000200
  17382. æC 
  17383.  
  17384. æKY priorityMask
  17385. æFc EPPC.h
  17386. æT #define
  17387. æD #define priorityMask 0x000000FF
  17388. æC 
  17389.  
  17390. æKY nAttnMsg
  17391. æFc EPPC.h
  17392. æT #define
  17393. æD #define nAttnMsg 0x00000001
  17394. æC 
  17395.  
  17396. æKY registerOnNetwork
  17397. æFc EPPC.h
  17398. æT #define
  17399. æD #define registerOnNetwork 0x80000000
  17400. æC 
  17401.  
  17402. æKY bufferIsSmall
  17403. æFc EPPC.h
  17404. æT #define
  17405. æD 
  17406. /*  error returns from Post and Accept */
  17407.  */
  17408.  
  17409. #define bufferIsSmall -607
  17410. æC 
  17411.  
  17412. æKY noOutstandingHLE
  17413. æFc EPPC.h
  17414. æT #define
  17415. æD #define noOutstandingHLE -608
  17416. æC 
  17417.  
  17418. æKY connectionInValid
  17419. æFc EPPC.h
  17420. æT #define
  17421. æD #define connectionInValid -609
  17422. æC 
  17423.  
  17424. æKY HighLevelEventMsgClass
  17425. æFc EPPC.h
  17426. æT #define
  17427. æD 
  17428. /*  constant for return receipts */
  17429.  */
  17430.  
  17431. #define HighLevelEventMsgClass 'jaym'
  17432. æC 
  17433.  
  17434. æKY rtrnReciptMsgID
  17435. æFc EPPC.h
  17436. æT #define
  17437. æD #define rtrnReciptMsgID 'rtrn'
  17438. æC 
  17439.  
  17440. æKY msgWasPartiallyAccepted
  17441. æFc EPPC.h
  17442. æT #define
  17443. æD #define msgWasPartiallyAccepted 2
  17444. æC 
  17445.  
  17446. æKY msgWasFullyAccepted
  17447. æFc EPPC.h
  17448. æT #define
  17449. æD #define msgWasFullyAccepted 1
  17450. æC 
  17451.  
  17452. æKY msgWasNotAccepted
  17453. æFc EPPC.h
  17454. æT #define
  17455. æD #define msgWasNotAccepted 0
  17456. æC 
  17457.  
  17458. æKY GetSpecificFilterProcPtr
  17459. æFc EPPC.h
  17460. æT typedef
  17461. æD typedef pascal Boolean (*GetSpecificFilterProcPtr) (unsigned long *param, HighLevelEventMsgPtr msgBuff, TargetID *sender);
  17462. æC 
  17463.  
  17464. æKY TargetID
  17465. TargetIDPtr
  17466. æFc EPPC.h
  17467. æT struct
  17468. æD struct TargetID {
  17469.     long sessionID;
  17470.     PortName name;
  17471.     LocName location;
  17472.     PortName recvrName;
  17473. };
  17474.  
  17475. typedef struct TargetID TargetID;
  17476. typedef TargetID *TargetIDPtr;
  17477.  
  17478. typedef struct TargetID SenderID, *SenderIDPtr;
  17479.  
  17480.  
  17481. æC 
  17482.  
  17483. æKY HighLevelEventMsg
  17484. HighLevelEventMsgPtr
  17485. HighLevelEventMsgHdl
  17486. æFc EPPC.h
  17487. æT struct
  17488. æD struct HighLevelEventMsg {
  17489.     long sessionID;
  17490.     unsigned short HighLevelEventMsgHeaderLength;
  17491.     unsigned short version;
  17492.     unsigned long reserved1;
  17493.     EventRecord theMsgEvent;
  17494.     unsigned long userRefcon;
  17495.     unsigned long postingOptions;
  17496.     unsigned long msgLength;
  17497. };
  17498.  
  17499. typedef struct HighLevelEventMsg HighLevelEventMsg;
  17500. typedef HighLevelEventMsg *HighLevelEventMsgPtr, **HighLevelEventMsgHdl;
  17501.  
  17502. æC 
  17503.  
  17504. æKY PostHighLevelEvent
  17505. æFc EPPC.h
  17506. æT Function
  17507. æTN A88F
  17508. æD 
  17509. pascal OSErr PostHighLevelEvent(EventRecord *theEvent,unsigned long receiverID,
  17510.     unsigned long msgRefcon,Ptr msgBuff,unsigned long msgLen,unsigned long postingOptions)
  17511.     = {0x3F3C,0x0034,0xA88F}; 
  17512. æDT OSErr myVariable = PostHighLevelEvent((EventRecord *) theEvent,(unsigned long) receiverID,(
  17513.     unsigned) long msgRefcon,(Ptr) msgBuff,(unsigned long) msgLen,(unsigned long) postingOptions);
  17514. æC 
  17515. You can use the PostHighLevelEvent routine to send a high-level event to another
  17516. application.
  17517.  
  17518. You specify the event to send in parameter theEvent, and include any additional
  17519. data for the event by providing a pointer to a data buffer in the msgBuff
  17520. parameter. The msgLen parameter specifies the size of the data buffer. The
  17521. receiverID parameter specifies the recipient of the event. The msgRefcon
  17522. parameter specifies a unique number associated with this event. Your application
  17523. can set this field to any value it chooses.
  17524.  
  17525. You can specify the receiver of the event by session ID, process serial number,
  17526. signature, or port name and port location. You can use any of these
  17527. specifications to send an event to another application on the local machine. You
  17528. can use only the session ID or port name and port location to send an event to
  17529. an application on a remote machine.
  17530.  
  17531. You use the postingOptions parameter to specify delivery options and options
  17532. associated with the receiverID parameter. You can specify one or more delivery
  17533. options to indicate whether you want the other application to receive the event
  17534. at the next opportunity, and to indicate whether you want acknowledgment that
  17535. the event was received by the other application. You use the options associated
  17536. with the receiverID parameter to indicate how you are specifying the recipient
  17537. of the event.
  17538.  
  17539. Result codes
  17540. noErr                 0  Mo error
  17541. connectionInValid  –609  Connection is invalid
  17542.  
  17543. æKY AcceptHighLevelEvent
  17544. æFc EPPC.h
  17545. æT Function
  17546. æTN A88F
  17547. æD 
  17548. pascal OSErr AcceptHighLevelEvent(TargetID *sender,unsigned long *msgRefcon,
  17549.     Ptr msgBuff,unsigned long *msgLen)
  17550.     = {0x3F3C,0x0033,0xA88F}; 
  17551. æDT OSErr myVariable = AcceptHighLevelEvent((TargetID *) sender,(unsigned long *) msgRefcon,()
  17552.     Ptr msgBuff,(unsigned long *) msgLen);
  17553. æC 
  17554. Some high-level events may be fully specified by their event record only, while
  17555. others may include additional information in an optional buffer. To get any
  17556. additional information and to find the sender of the event, use the
  17557. AcceptHighLevelEvent function.
  17558.  
  17559. The sender of the event is specified in the sender parameter, which is a pointer
  17560. to a TargetID data structure. The sender parameter contains the session
  17561. reference number that identifes this communication and the port name and port
  17562. location of the sender.
  17563.  
  17564. The msgRefcon parameter is a unique number that is used to identify this event.
  17565. If you send a response to this event, you should specify the same value of
  17566. msgRefcon so that the sender of the event can associate the reply with the
  17567. original request.
  17568.  
  17569. The msgBuff parameter points to any additional data associated with the event.
  17570. The msgLen parameter contains the size of the buffer. Your application is
  17571. responsible for allocating the memory for the additional data pointed to by the
  17572. msgBuff parameter. If the msgBuff parameter points to an area in memory that is
  17573. not large enough to hold all the data associated with the event,
  17574. AcceptHighLevelEvent returns the result code bufferIsSmall. If
  17575. AcceptHighLevelEvent returns the result code bufferIsSmall, the msgLen parameter
  17576. contains the number of bytes remaining. You can call AcceptHighLevelEvent again
  17577. to receive the rest of the data.
  17578.  
  17579. Result codes
  17580. noErr                0  No error
  17581. bufferIsSmall     –607  Buffer is too small
  17582. noOutstandingHLE  –608  No outstanding high-level event
  17583.  
  17584. æKY GetProcessSerialNumberFromPortName
  17585. æFc EPPC.h
  17586. æT Function
  17587. æTN A88F
  17588. æD pascal OSErr GetProcessSerialNumberFromPortName(PortNamePtr portName,ProcessSerialNumberPtr pPSN)
  17589.     = {0x3F3C,0x0035,0xA88F}; 
  17590. æDT OSErr myVariable = GetProcessSerialNumberFromPortName((PortNamePtr) portName,(ProcessSerialNumberPtr) pPSN);
  17591. æC 
  17592.  
  17593. æKY GetPortNameFromProcessSerialNumber
  17594. æFc EPPC.h
  17595. æT Function
  17596. æTN A88F
  17597. æD pascal OSErr GetPortNameFromProcessSerialNumber(PortNamePtr portName,ProcessSerialNumberPtr pPSN)
  17598.     = {0x3F3C,0x0046,0xA88F}; 
  17599. æDT OSErr myVariable = GetPortNameFromProcessSerialNumber((PortNamePtr) portName,(ProcessSerialNumberPtr) pPSN);
  17600. æC 
  17601.  
  17602. æKY GetSpecificHighLevelEvent
  17603. æFc EPPC.h
  17604. æT Function
  17605. æTN A88F
  17606. æD 
  17607. pascal Boolean GetSpecificHighLevelEvent(GetSpecificFilterProcPtr aFilter,
  17608.     unsigned long *params,OSErr *err)
  17609.     = {0x3F3C,0x0045,0xA88F}; 
  17610. æDT Boolean myVariable = GetSpecificHighLevelEvent((GetSpecificFilterProcPtr) aFilter,(
  17611.     unsigned long) * params,(OSErr *) err);
  17612. æC 
  17613. You can use the GetSpecificHighLevelEvent function to select and optionally
  17614. retrieve a specific high-level event from the high-level event queue.
  17615.  
  17616. You specify your filter function in the aFilter parameter.
  17617. GetSpecificHighLevelEvent calls your filter function once for each event on the
  17618. high-level event queue until your filter function returns TRUE or the end of the
  17619. queue is reached. You use the params parameter to specify the criteria your
  17620. filter function should use to select a specific event. For example, you can
  17621. specify the params parameter as a msgRefcon value to search for a particular
  17622. event or as a pointer to a targetID structure to search for a specific sender of
  17623. an event. Or you can search for a specific class of event.
  17624.  
  17625. Here’s how you declare the filter function aFilter:
  17626.  
  17627. FUNCTION aFilter (VAR params: LongInt; msgBuff: HighLevelEventMsgPtr;
  17628.                   sender: TargetID) : Boolean;
  17629.  
  17630. The params parameter indicates the criteria your filter function should use to
  17631. search for a specific event. The msgBuff parameter contains a pointer to a
  17632. record of type HighLevelEventMsg, which provides information about the event:
  17633. the event record for the high-level event, the posting options of the event, and
  17634. so forth. The sender parameter contains the target ID of the application that
  17635. sent the event.
  17636.  
  17637. Your filter function can compare the contents of the params parameter with the
  17638. contents of the msgBuff or senderID parameters. If your filter function finds a
  17639. match, your filter function should return TRUE. If it does not find a match,
  17640. your filter function should return FALSE.
  17641.  
  17642.  
  17643. æKY ErrMgr.h
  17644. æKL AddErrInsert
  17645. addInserts
  17646. CloseErrMgr
  17647. GetSysErrText
  17648. GetToolErrText
  17649. InitErrMgr
  17650.  
  17651.  
  17652. æKY AddErrInsert
  17653. æFc ErrMgr.h
  17654. æT Function
  17655. æD void AddErrInsert(unsigned char *insert,unsigned char *msgString);
  17656. æDT AddErrInsert((unsigned char *)insert,(unsigned char *)msgString);
  17657. æC 
  17658. /* 
  17659.     Add another insert to an error message string.This call is used when more
  17660.     than one insert is to be added to a message (because it contains more than
  17661.     one '^' character).
  17662. */
  17663.  
  17664. æKY addInserts
  17665. æFc ErrMgr.h
  17666. æT Function
  17667. æD unsigned char *addInserts(unsigned char *msgString,unsigned char *insert,
  17668.     ...);
  17669. æDT unsigned char myVariable = addInserts((unsigned char *)msgString,(unsigned char *)insert,
  17670.     (...));
  17671. æC 
  17672. /* 
  17673.     Add a set of inserts to an error message string.  AddErrInsert is called for
  17674.     each insert parameter specified.
  17675. */
  17676.  
  17677. æKY CloseErrMgr
  17678. æFc ErrMgr.h
  17679. æT Function
  17680. æD void CloseErrMgr(void);
  17681. æDT CloseErrMgr();
  17682. æC 
  17683. /* 
  17684.     Ideally a CloseErrMgr should be done at the end of execution to make sure all
  17685.     files opened by the ErrMgr are closed.  You can let normal program termination
  17686.     do the closing.  But if you are a purist...
  17687. */
  17688.  
  17689. æKY GetSysErrText
  17690. æFc ErrMgr.h
  17691. æT Function
  17692. æD char *GetSysErrText(short msgNbr,char *errMsg);
  17693. æDT char myVariable = GetSysErrText((short)msgNbr,(char *)errMsg);
  17694. æC 
  17695. /* 
  17696.     Get the error message text corresponding to system error number errNbr from
  17697.     the system error message file (whose name was specified in the InitErrMgr
  17698.     call).  The text of the message is returned in errMsg and the function returns
  17699.     a pointer to errMsg.  The maximum length of the message is limited to 254
  17700.     characters.
  17701.     
  17702.     Note, if a system message filename was not specified to InitErrMgr, then the
  17703.     ErrMgr assumes the message file contained in the file "SysErrs.Err".  This
  17704.     file is first accessed as "{ShellDirectory}SysErrs.Err" on the assumption that
  17705.     SysErrs.Err is kept in the same directory as the MPW Shell.  If the file
  17706.     cannot be opened, then an open is attempted on "SysErrs.Err" in the System
  17707.     Folder.
  17708. */
  17709.  
  17710.  
  17711. æKY GetToolErrText
  17712. æFc ErrMgr.h
  17713. æT Function
  17714. æD char *GetToolErrText(short msgNbr,char *errInsert,char *errMsg);
  17715. æDT char myVariable = GetToolErrText((short)msgNbr,(char *)errInsert,(char *)errMsg);
  17716. æC 
  17717. /* 
  17718.     Get the error message text corresponding to tool error number errNbr from
  17719.     the tool error message file (whose name was specified in the InitErrMgr
  17720.     call).  The text of the message is returned in errMsg and the function returns
  17721.     a pointer to errMsg.  The maximum length of the message is limited to 254
  17722.     characters.  If the message is to have an insert, then ErrInsert should be a
  17723.     pointer to it.  Otherwise it should be either be a null string or a NULL
  17724.     pointer.
  17725.     
  17726.     Inserts are indicated in error messages by specifying a '^' to indicate where
  17727.     the insert is to be placed.
  17728.     
  17729.     Note, if a tool message filename was not specified to InitErrMgr, then the
  17730.     ErrMgr assumes the message file contained in the data fork of the tool calling
  17731.     the ErrMgr.  This name is contained in the Shell variable {Command} and the
  17732.     value of that variable is used to open the error message file.
  17733. */
  17734.  
  17735. æKY InitErrMgr
  17736. æFc ErrMgr.h
  17737. æT Function
  17738. æD void InitErrMgr(char *toolErrFilename,char *sysErrFilename,Boolean showToolErrNbrs);
  17739. æDT InitErrMgr((char *)toolErrFilename,(char *)sysErrFilename,
  17740.     (Boolean)showToolErrNbrs);
  17741. æC 
  17742. /* 
  17743.     ErrMgr initialization.This must be done before using any other ErrMgr
  17744.     routine.  Set showToolErrNbrs to true if you want all tool messages to contain
  17745.     the error number following the message text enclosed in parentheses (e.g.,
  17746.     "<msg txt> ([OS] Error <n>)"; system error messages always contain the error 
  17747.     number).  The toolErrFileName parameter is used to specify the name of a 
  17748.     tool-specific error file, and should be the NULL or a null string if not used
  17749.     (or if the tool's data fork is to be used as the error file, see
  17750.     GetToolErrText for futher details). The sysErrFileName parameter is used to
  17751.     specify the name of a system error file, and should normally be the NULL or a
  17752.     null string, which causes the ErrMgr to look in the MPW Shell directory for
  17753.     "SysErrs.Err" (see GetSysErrText).
  17754.     
  17755.     If InitErrMgr is NOT called prior to calling GetSysErrText or GetToolErrText,
  17756.     then those routines, the first time they are called, will call InitErrMgr as
  17757.     InitErrMgr(NULL, NULL, true).
  17758.     
  17759.     The following global may be set to true to allow a C caller to process all
  17760.     strings as Pascal strings:*/
  17761.     
  17762.     extern Boolean pascalStrings;   /* set to true for Pascal strings*//*
  17763.     
  17764.     This should be set PRIOR to calling InitErrMgr.  Once set, ALL strings, both
  17765.     those passed to the ErrMgr as filenames and error message inserts, as well as
  17766.     the messages returned by the ErrMgr will be Pascal strings.  There is NO
  17767.     guarantee a '\0' byte is at the end of the string.  Results are unpredictable
  17768.     if pascalStringsis set false after it has been set true!
  17769.     
  17770. */
  17771.  
  17772.  
  17773. æKY ErrNo.h
  17774. æFc ErrNo.h
  17775. æC Synopsis
  17776.  
  17777. #include <ErrNo.h>
  17778. extern int errno;
  17779. extern short MacOSErr;
  17780.  
  17781.                            Description
  17782.  
  17783. Many of the Standard C Library functions can return, in 
  17784. addition to their normal return values, a negative value 
  17785. indicating an error, typically –1. For example, a function 
  17786. returning a character as an int will indicate an error by 
  17787. returning –1, which is not a legitimate ASCII value. (See the 
  17788. Descriptions of individual functions for details.) The external 
  17789. variable errno also provides an error number. Variable errno is 
  17790. not cleared on successful calls, so it should be tested only if 
  17791. the return value indicates an error.
  17792.  
  17793. The error name appears in brackets following the text in a 
  17794. library function description: for example,
  17795. “The next attempt to write a nonzero number of bytes will 
  17796. signal an error. [ENOSPC]”
  17797.  
  17798. Not all possible error numbers are listed for each library 
  17799. function because many errors are possible for most of the 
  17800. calls. Some UNIX operating system error numbers do not apply 
  17801. to Macintosh and are not documented in this manual. Some calls 
  17802. go to the Macintosh ROM and return a value in MacOSErr as well 
  17803. as the value in errno.
  17804.  
  17805. Table 3-2 is a list of the error numbers and their names as 
  17806. defined in the <ErrNo.h> file. Not all the error numbers listed 
  17807. here will be returned, but they are included in the header file 
  17808. for compatibility.
  17809.  
  17810. Table 3-2    I/O errors
  17811. Value    Identifier  Message Explanation
  17812.  
  17813.   1      EPERM       No permission match An attempt was made to 
  17814.                      modify a file in some way forbidden except to its 
  17815.                      creator.
  17816.   2      ENOENT      No such file or directory   A file whose filename is 
  17817.                      specified does not exist, or one of the directories 
  17818.                      in a pathname does not exist.
  17819.   3      ENORSRC     Resource not found  A required resource was not found.
  17820.                      This error applies to faccess calls that return tab, 
  17821.                      font, or print record information.
  17822.   4      EINTR       System service interrupted  A requested system 
  17823.                      call cannot be completed. 
  17824.                      This error may occur if a request to rename a file 
  17825.                      is unsuccessful.
  17826.   5      EIO         I/O error   Some physical I/O error has occurred. 
  17827.                      This error may in some cases be signaled on a call 
  17828.                      following the one to which it actually applies.
  17829.   6      ENXIO       No such device or address   I/O on a special file 
  17830.                      refers to a subdevice that does not exist, or the I/O 
  17831.                      is beyond the limits of the device. This error 
  17832.                      may also occur when, for example, no disk is 
  17833.                      present in a drive.
  17834.   7      E2BIG       Insufficient space for  The data to be returned 
  17835.                      is too large for the space allocated to receive it.
  17836.   9      EBADF       Bad file number Either a file descriptor 
  17837.                      does not refer to an open file, or a read (or write) 
  17838.                      request is made to a file that is open only for 
  17839.                      writing (or reading).
  17840.  12      ENOMEM      Not enough space. The system ran out of 
  17841.                      memory while the library call was executing.
  17842.  13      EACCES      Permission denied. An attempt was made to access 
  17843.                      a file in a way forbidden by the protection system.
  17844.  14      EFAULT      Illegal filename. A filename or volume name was too 
  17845.                      long or otherwise illegal.
  17846.  15      ENOTBLK     Block device required. A non-block file was 
  17847.                      used when a block device was required.
  17848.  16      EBUSY       Device or resource busy. An attempt was made to 
  17849.                      mount a volume that was already mounted, or to 
  17850.                      delete a locked file.
  17851.  17      EEXIST      File exists. An existing file was mentioned in an 
  17852.                      inappropriate context; for example, open(file, 
  17853.                      O_CREAT+O_EXCL).
  17854.  18      EXDEV       Cross-device link. A link to a file on another 
  17855.                      device was attempted.
  17856.  19      ENODEV      No such device. An attempt was made to apply an 
  17857.                      inappropriate system call to a device; 
  17858.                      for example, read a write-only device.
  17859.  20      ENOTDIR     Not a directory. An object that is not a directory
  17860.                      was specified where a directory is required; 
  17861.                      for example, in a path prefix.
  17862.  21      EISDIR      Is a directory. An attempt was made to 
  17863.                      write on a directory.
  17864.  22      EINVAL      Invalid parameter. Some invalid parameter 
  17865.                      was provided to a library function.
  17866.  23      ENFILE      File table overflow. The system’s table of open
  17867.                      files is full, so temporarily a call to open 
  17868.                      cannot be accepted.
  17869.  24      EMFILE      Too many open files. The system cannot allocate
  17870.                      memory to record another open file.
  17871.  25      ENOTTY      Not a typewriter. The specified file isn’t a 
  17872.                      character file.
  17873.  26      ETXTBSY     Text file busy. An attempt was made to open
  17874.                      a file that was already open for writing.
  17875.  27      EFBIG       File too large. The size of a file was 
  17876.                      larger than the maximum file size.
  17877.  28      ENOSPC      No space left on device. During a write to a file, 
  17878.                      there is no free space left on the device.
  17879.  29      ESPIPE      Illegal seek. An lseek was issued incorrectly.
  17880.  30      EROFS       Read-only file system. An attempt to modify a 
  17881.                      file or directory was made on a device 
  17882.                      mounted for read-only access.
  17883.  31      EMLINK      Too many links. An attempt to delete an 
  17884.                      open file was made.
  17885.  33      EDOM        Math arg out of domain of func. The argument of a 
  17886.                      math function is outside the domain of the 
  17887.                      function.
  17888.  34      ERANGE      Math result not representable. The value of a math 
  17889.                      function can’t be represented within the 
  17890.                      machine’s precision.
  17891.  
  17892.                            Note
  17893.  
  17894. Calls that interface to the Macintosh I/O system (such as open, 
  17895. close, read, write, and ioctl) can set the external variable 
  17896. MacOSErr as well as errno on errors. This section documents the 
  17897. errno values. The equivalent Macintosh ROM error-return 
  17898. values set in MacOSErr are documented in the System Error 
  17899. Handler chapter of Inside Macintosh.
  17900.  
  17901. See also
  17902. hypot, signal, perror, creat, open, close, read, write, ioctl
  17903.  
  17904.  
  17905. æKY Errors.h
  17906. æKL SysError
  17907.  
  17908. abortErr
  17909. addRefFailed
  17910. addResFailed
  17911. afpAccessDenied
  17912. afpAuthContinue
  17913. afpBadUAM
  17914. afpBadVersNum
  17915. afpBitmapErr
  17916. afpCallNotSupported
  17917. afpCantMove
  17918. afpCantRename
  17919. afpDenyConflict
  17920. afpDirNotEmpty
  17921. afpDirNotFound
  17922. afpDiskFull
  17923. afpEofError
  17924. afpFileBusy
  17925. afpFlatVol
  17926. afpIconTypeError
  17927. afpItemNotFound
  17928. afpLockErr
  17929. afpMiscErr
  17930. afpNoMoreLocks
  17931. afpNoServer
  17932. afpObjectExists
  17933. afpObjectLocked
  17934. afpObjectNotFound
  17935. afpObjectTypeErr
  17936. afpParmErr
  17937. afpRangeNotLocked
  17938. afpRangeOverlap
  17939. afpServerGoingDown
  17940. afpSessClosed
  17941. afpTooManyFilesOpen
  17942. afpUserNotAuth
  17943. afpVolLocked
  17944. aspBadVersNum
  17945. aspBufTooSmall
  17946. aspNoAck
  17947. aspNoMoreSess
  17948. aspNoServers
  17949. aspParamErr
  17950. aspServerBusy
  17951. aspSessClosed
  17952. aspSizeErr
  17953. aspTooMany
  17954. atpBadRsp
  17955. atpLenErr
  17956. badATPSkt
  17957. badBtSlpErr
  17958. badBuffNum
  17959. badChannel
  17960. badCksmErr
  17961. badDBtSlp
  17962. badDCksum
  17963. badEditionFileErr
  17964. badFormat
  17965. badMDBErr
  17966. badMovErr
  17967. badSectionErr
  17968. badSubPartErr
  17969. badUnitErr
  17970. bdNamErr
  17971. breakRecd
  17972. buf2SmallErr
  17973. cantStepErr
  17974. catChangedErr
  17975. cbNotFound
  17976. cDevErr
  17977. ckSumErr
  17978. clkRdErr
  17979. clkWrErr
  17980. closErr
  17981. cMatchErr
  17982. cNoMemErr
  17983. containerAlreadyOpenWrn
  17984. containerNotFoundWrn
  17985. controlErr
  17986. corErr
  17987. cProtectErr
  17988. cRangeErr
  17989. cResErr
  17990. cTempMemErr
  17991. dataVerErr
  17992. dceExtErr
  17993. ddpLenErr
  17994. ddpSktErr
  17995. DiffVolErr
  17996. dInstErr
  17997. dirFulErr
  17998. dirNFErr
  17999. dRemovErr
  18000. dsAddressErr
  18001. dsBadLaunch
  18002. dsBadPatch
  18003. dsBadSANEopcode
  18004. dsBadSlotInt
  18005. dsBusError
  18006. dsChkErr
  18007. dsCoreErr
  18008. dsFinderErr
  18009. dsFPErr
  18010. dsFSErr
  18011. dsGreeting
  18012. dsHMenuFindErr
  18013. dsIllInstErr
  18014. dsIOCoreErr
  18015. dsIrqErr
  18016. dskFulErr
  18017. dsLineAErr
  18018. dsLineFErr
  18019. dsLoadErr
  18020. dsMBarNFnd
  18021. dsMemFullErr
  18022. dsMiscErr
  18023. dsNoPackErr
  18024. dsNoPatch
  18025. dsNoPk1
  18026. dsNoPk2
  18027. dsNoPk3
  18028. dsNoPk4
  18029. dsNoPk5
  18030. dsNoPk6
  18031. dsNoPk7
  18032. dsNotThe1
  18033. dsOvflowErr
  18034. dsPrivErr
  18035. dsReinsert
  18036. dsStknHeap
  18037. dsSysErr
  18038. dsTraceErr
  18039. dsZeroDivErr
  18040. dupFNErr
  18041. editionMgrInitErr
  18042. envBadVers
  18043. envNotPresent
  18044. envVersTooBig
  18045. eofErr
  18046. evtNotEnb
  18047. excessCollsns
  18048. extFSErr
  18049. extractErr
  18050. exUserBreak
  18051. fBsyErr
  18052. fidExists
  18053. fidNotFound
  18054. firstDskErr
  18055. fLckdErr
  18056. fmt1Err
  18057. fmt2Err
  18058. fnfErr
  18059. fnOpnErr
  18060. fontDecError
  18061. fontNotDeclared
  18062. fontSubErr
  18063. framingErr
  18064. fsDSIntErr
  18065. fsRnErr
  18066. gcrOnMFMErr
  18067. gfpErr
  18068. hMenuFindErr
  18069. hwOverrunErr
  18070. hwParamErr
  18071. iIOAbortErr
  18072. initIWMErr
  18073. ioErr
  18074. lapProtErr
  18075. lastDskErr
  18076. MacOSErr
  18077. mapReadErr
  18078. mBarNFnd
  18079. memAdrErr
  18080. memAZErr
  18081. memBCErr
  18082. memFullErr
  18083. memLockedErr
  18084. memPCErr
  18085. memPurErr
  18086. memROZErr
  18087. memROZWarn
  18088. memSCErr
  18089. memWZErr
  18090. menuPrgErr
  18091. mFulErr
  18092. multiplePublisherWrn
  18093. nbpBuffOvr
  18094. nbpConfDiff
  18095. nbpDuplicate
  18096. nbpNISErr
  18097. nbpNoConfirm
  18098. nbpNotFound
  18099. negZcbFreeErr
  18100. nilHandleErr
  18101. nmTypErr
  18102. noAdrMkErr
  18103. noBridgeErr
  18104. noDataArea
  18105. noDriveErr
  18106. noDtaMkErr
  18107. noHardware
  18108. noMacDskErr
  18109. noMPPErr
  18110. noNybErr
  18111. noRelErr
  18112. noScrapErr
  18113. noSendResp
  18114. NotAFileErr
  18115. notEnoughHardware
  18116. notOpenErr
  18117. notRegisteredSectionErr
  18118. notThePublisherWrn
  18119. noTypeErr
  18120. nsDrvErr
  18121. nsvErr
  18122. offLinErr
  18123. openErr
  18124. opWrErr
  18125. paramErr
  18126. parityErr
  18127. permErr
  18128. pixMapTooDeepErr
  18129. portInUse
  18130. portNotCf
  18131. posErr
  18132. prInitErr
  18133. prWrErr
  18134. qErr
  18135. queueFull
  18136. rcvrErr
  18137. readErr
  18138. readQErr
  18139. recNotFnd
  18140. reqAborted
  18141. reqFailed
  18142. resAttrErr
  18143. resFNotFound
  18144. resNotFound
  18145. resProblem
  18146. rfNumErr
  18147. rgnTooBigErr
  18148. rmvRefFailed
  18149. rmvResFailed
  18150. sdmInitErr
  18151. sdmJTInitErr
  18152. sdmPRAMInitErr
  18153. sdmPriInitErr
  18154. sdmSRTInitErr
  18155. sectNFErr
  18156. seekErr
  18157. seNoDB
  18158. shutDownAlert
  18159. siInitSDTblErr
  18160. siInitSPTblErr
  18161. siInitVBLQsErr
  18162. sktClosedErr
  18163. slotNumErr
  18164. smBadBoardId
  18165. smBadRefId
  18166. smBadsList
  18167. smBadsPtrErr
  18168. smBLFieldBad
  18169. smBlkMoveErr
  18170. smBusErrTO
  18171. smByteLanesErr
  18172. smCkStatusErr
  18173. smCodeRevErr
  18174. smCPUErr
  18175. smCRCFail
  18176. smDisDrvrNamErr
  18177. smDisposePErr
  18178. smEmptySlot
  18179. smFHBlockRdErr
  18180. smFormatErr
  18181. smGetDrvrNamErr
  18182. smGetPRErr
  18183. smInitStatVErr
  18184. smInitTblErr
  18185. smLWTstBad
  18186. smNewPErr
  18187. smNilsBlockErr
  18188. smNoBoardId
  18189. smNoBoardsRsrc
  18190. smNoDir
  18191. smNoGoodOpens
  18192. smNoJmpTbl
  18193. smNoMoresRsrcs
  18194. smNosInfoArray
  18195. smOffsetErr
  18196. smPRAMInitErr
  18197. smPriInitErr
  18198. smRecNotFnd
  18199. smReservedErr
  18200. smResrvErr
  18201. smRevisionErr
  18202. smSDMInitErr
  18203. smSelOOBErr
  18204. smsGetDrvrErr
  18205. smSlotOOBErr
  18206. smsPointerNil
  18207. smSRTInitErr
  18208. smSRTOvrFlErr
  18209. smUnExBusErr
  18210. spdAdjErr
  18211. statusErr
  18212. strUserBreak
  18213. svDisabled
  18214. svTempDisable
  18215. swOverrunErr
  18216. teScrapSizeErr
  18217. tk0BadErr
  18218. tmfoErr
  18219. tmwdoErr
  18220. tooManyReqs
  18221. tooManySkts
  18222. twoSideErr
  18223. unimpErr
  18224. unitEmptyErr
  18225. unitTblFullErr
  18226. updPixMemErr
  18227. userBreak
  18228. userCanceledErr
  18229. verErr
  18230. vLckdErr
  18231. volGoneErr
  18232. volOffLinErr
  18233. volOnLinErr
  18234. vTypErr
  18235. wPrErr
  18236. wrgVolTypErr
  18237. writErr
  18238. wrPermErr
  18239. wrUnderrun
  18240.  
  18241. æKY qErr
  18242. æFc Errors.h
  18243. æT #define
  18244. æD #define qErr -1 /*queue element not found during deletion*/
  18245. æC 
  18246.  
  18247. æKY vTypErr
  18248. æFc Errors.h
  18249. æT #define
  18250. æD #define vTypErr -2 /*invalid queue element*/
  18251. æC 
  18252.  
  18253. æKY corErr
  18254. æFc Errors.h
  18255. æT #define
  18256. æD #define corErr -3 /*core routine number out of range*/
  18257. æC 
  18258.  
  18259. æKY unimpErr
  18260. æFc Errors.h
  18261. æT #define
  18262. æD #define unimpErr -4 /*unimplemented core routine*/
  18263. æC 
  18264.  
  18265. æKY seNoDB
  18266. æFc Errors.h
  18267. æT #define
  18268. æD #define seNoDB -8 /*no debugger installed to handle debugger command*/
  18269. æC 
  18270.  
  18271. æKY controlErr
  18272. æFc Errors.h
  18273. æT #define
  18274. æD #define controlErr -17 /*I/O System Errors*/
  18275. æC 
  18276.  
  18277. æKY statusErr
  18278. æFc Errors.h
  18279. æT #define
  18280. æD #define statusErr -18 /*I/O System Errors*/
  18281. æC 
  18282.  
  18283. æKY readErr
  18284. æFc Errors.h
  18285. æT #define
  18286. æD #define readErr -19 /*I/O System Errors*/
  18287. æC 
  18288.  
  18289. æKY writErr
  18290. æFc Errors.h
  18291. æT #define
  18292. æD #define writErr -20 /*I/O System Errors*/
  18293. æC 
  18294.  
  18295. æKY badUnitErr
  18296. æFc Errors.h
  18297. æT #define
  18298. æD #define badUnitErr -21 /*I/O System Errors*/
  18299. æC 
  18300.  
  18301. æKY unitEmptyErr
  18302. æFc Errors.h
  18303. æT #define
  18304. æD #define unitEmptyErr -22 /*I/O System Errors*/
  18305. æC 
  18306.  
  18307. æKY openErr
  18308. æFc Errors.h
  18309. æT #define
  18310. æD #define openErr -23 /*I/O System Errors*/
  18311. æC 
  18312.  
  18313. æKY closErr
  18314. æFc Errors.h
  18315. æT #define
  18316. æD #define closErr -24 /*I/O System Errors*/
  18317. æC 
  18318.  
  18319. æKY dRemovErr
  18320. æFc Errors.h
  18321. æT #define
  18322. æD #define dRemovErr -25 /*tried to remove an open driver*/
  18323. æC 
  18324.  
  18325. æKY dInstErr
  18326. æFc Errors.h
  18327. æT #define
  18328. æD #define dInstErr -26 /*DrvrInstall couldn't find driver in resources */
  18329. æC 
  18330.  
  18331. æKY abortErr
  18332. æFc Errors.h
  18333. æT #define
  18334. æD #define abortErr -27 /*IO call aborted by KillIO*/
  18335. æC 
  18336.  
  18337. æKY iIOAbortErr
  18338. æFc Errors.h
  18339. æT #define
  18340. æD #define iIOAbortErr -27 /*IO abort error (Printing Manager)*/
  18341. æC 
  18342.  
  18343. æKY notOpenErr
  18344. æFc Errors.h
  18345. æT #define
  18346. æD #define notOpenErr -28 /*Couldn't rd/wr/ctl/sts cause driver not opened*/
  18347. æC 
  18348.  
  18349. æKY dirFulErr
  18350. æFc Errors.h
  18351. æT #define
  18352. æD #define dirFulErr -33 /*Directory full*/
  18353. æC 
  18354.  
  18355. æKY dskFulErr
  18356. æFc Errors.h
  18357. æT #define
  18358. æD #define dskFulErr -34 /*disk full*/
  18359. æC 
  18360.  
  18361. æKY nsvErr
  18362. æFc Errors.h
  18363. æT #define
  18364. æD #define nsvErr -35 /*no such volume*/
  18365. æC 
  18366.  
  18367. æKY ioErr
  18368. æFc Errors.h
  18369. æT #define
  18370. æD #define ioErr -36 /*I/O error (bummers)*/
  18371. æC 
  18372.  
  18373. æKY bdNamErr
  18374. æFc Errors.h
  18375. æT #define
  18376. æD #define bdNamErr -37 /*there may be no bad names in the final system!*/
  18377. æC 
  18378.  
  18379. æKY fnOpnErr
  18380. æFc Errors.h
  18381. æT #define
  18382. æD #define fnOpnErr -38 /*File not open*/
  18383. æC 
  18384.  
  18385. æKY eofErr
  18386. æFc Errors.h
  18387. æT #define
  18388. æD #define eofErr -39 /*End of file*/
  18389. æC 
  18390.  
  18391. æKY posErr
  18392. æFc Errors.h
  18393. æT #define
  18394. æD #define posErr -40 /*tried to position to before start of file (r/w)*/
  18395. æC 
  18396.  
  18397. æKY mFulErr
  18398. æFc Errors.h
  18399. æT #define
  18400. æD #define mFulErr -41 /*memory full (open) or file won't fit (load)*/
  18401. æC 
  18402.  
  18403. æKY tmfoErr
  18404. æFc Errors.h
  18405. æT #define
  18406. æD #define tmfoErr -42 /*too many files open*/
  18407. æC 
  18408.  
  18409. æKY fnfErr
  18410. æFc Errors.h
  18411. æT #define
  18412. æD #define fnfErr -43 /*File not found*/
  18413. æC 
  18414.  
  18415. æKY wPrErr
  18416. æFc Errors.h
  18417. æT #define
  18418. æD #define wPrErr -44 /*diskette is write protected.*/
  18419. æC 
  18420.  
  18421. æKY fLckdErr
  18422. æFc Errors.h
  18423. æT #define
  18424. æD #define fLckdErr -45 /*file is locked*/
  18425. æC 
  18426.  
  18427. æKY vLckdErr
  18428. æFc Errors.h
  18429. æT #define
  18430. æD #define vLckdErr -46 /*volume is locked*/
  18431. æC 
  18432.  
  18433. æKY fBsyErr
  18434. æFc Errors.h
  18435. æT #define
  18436. æD #define fBsyErr -47 /*File is busy (delete)*/
  18437. æC 
  18438.  
  18439. æKY dupFNErr
  18440. æFc Errors.h
  18441. æT #define
  18442. æD #define dupFNErr -48 /*duplicate filename (rename)*/
  18443. æC 
  18444.  
  18445. æKY opWrErr
  18446. æFc Errors.h
  18447. æT #define
  18448. æD #define opWrErr -49 /*file already open with with write permission*/
  18449. æC 
  18450.  
  18451. æKY paramErr
  18452. æFc Errors.h
  18453. æT #define
  18454. æD #define paramErr -50 /*error in user parameter list*/
  18455. æC 
  18456.  
  18457. æKY rfNumErr
  18458. æFc Errors.h
  18459. æT #define
  18460. æD #define rfNumErr -51 /*refnum error*/
  18461. æC 
  18462.  
  18463. æKY gfpErr
  18464. æFc Errors.h
  18465. æT #define
  18466. æD #define gfpErr -52 /*get file position error*/
  18467. æC 
  18468.  
  18469. æKY volOffLinErr
  18470. æFc Errors.h
  18471. æT #define
  18472. æD #define volOffLinErr -53 /*volume not on line error (was Ejected)*/
  18473. æC 
  18474.  
  18475. æKY permErr
  18476. æFc Errors.h
  18477. æT #define
  18478. æD #define permErr -54 /*permissions error (on file open)*/
  18479. æC 
  18480.  
  18481. æKY pixMapTooDeepErr
  18482. æFc Errors.h
  18483. æT #define
  18484. æD #define pixMapTooDeepErr -148
  18485. æC 
  18486.  
  18487. æKY volOnLinErr
  18488. æFc Errors.h
  18489. æT #define
  18490. æD #define volOnLinErr -55 /*drive volume already on-line at MountVol*/
  18491. æC 
  18492.  
  18493. æKY nsDrvErr
  18494. æFc Errors.h
  18495. æT #define
  18496. æD #define nsDrvErr -56 /*no such drive (tried to mount a bad drive num)*/
  18497. æC 
  18498.  
  18499. æKY noMacDskErr
  18500. æFc Errors.h
  18501. æT #define
  18502. æD #define noMacDskErr -57 /*not a mac diskette (sig bytes are wrong)*/
  18503. æC 
  18504.  
  18505. æKY extFSErr
  18506. æFc Errors.h
  18507. æT #define
  18508. æD #define extFSErr -58 /*volume in question belongs to an external fs*/
  18509. æC 
  18510.  
  18511. æKY fsRnErr
  18512. æFc Errors.h
  18513. æT #define
  18514. æD #define fsRnErr -59 /*file system internal error:during rename the old entry was deleted but could not be restored.*/
  18515. æC 
  18516.  
  18517. æKY badMDBErr
  18518. æFc Errors.h
  18519. æT #define
  18520. æD #define badMDBErr -60 /*bad master directory block*/
  18521. æC 
  18522.  
  18523. æKY wrPermErr
  18524. æFc Errors.h
  18525. æT #define
  18526. æD #define wrPermErr -61 /*write permissions error*/
  18527. æC 
  18528.  
  18529. æKY fontDecError
  18530. æFc Errors.h
  18531. æT #define
  18532. æD #define fontDecError -64 /*error during font declaration*/
  18533. æC 
  18534.  
  18535. æKY lastDskErr
  18536. æFc Errors.h
  18537. æT #define
  18538. æD #define lastDskErr -64 /*I/O System Errors*/
  18539. æC 
  18540.  
  18541. æKY noDriveErr
  18542. æFc Errors.h
  18543. æT #define
  18544. æD #define noDriveErr -64 /*drive not installed*/
  18545. æC 
  18546.  
  18547. æKY offLinErr
  18548. æFc Errors.h
  18549. æT #define
  18550. æD #define offLinErr -65 /*r/w requested for an off-line drive*/
  18551. æC 
  18552.  
  18553. æKY fontNotDeclared
  18554. æFc Errors.h
  18555. æT #define
  18556. æD #define fontNotDeclared -65 /*font not declared*/
  18557. æC 
  18558.  
  18559. æKY noNybErr
  18560. æFc Errors.h
  18561. æT #define
  18562. æD #define noNybErr -66 /*couldn't find 5 nybbles in 200 tries*/
  18563. æC 
  18564.  
  18565. æKY fontSubErr
  18566. æFc Errors.h
  18567. æT #define
  18568. æD #define fontSubErr -66 /*font substitution occured*/
  18569. æC 
  18570.  
  18571. æKY noAdrMkErr
  18572. æFc Errors.h
  18573. æT #define
  18574. æD #define noAdrMkErr -67 /*couldn't find valid addr mark*/
  18575. æC 
  18576.  
  18577. æKY dataVerErr
  18578. æFc Errors.h
  18579. æT #define
  18580. æD #define dataVerErr -68 /*read verify compare failed*/
  18581. æC 
  18582.  
  18583. æKY badCksmErr
  18584. æFc Errors.h
  18585. æT #define
  18586. æD #define badCksmErr -69 /*addr mark checksum didn't check*/
  18587. æC 
  18588.  
  18589. æKY badBtSlpErr
  18590. æFc Errors.h
  18591. æT #define
  18592. æD #define badBtSlpErr -70 /*bad addr mark bit slip nibbles*/
  18593. æC 
  18594.  
  18595. æKY noDtaMkErr
  18596. æFc Errors.h
  18597. æT #define
  18598. æD #define noDtaMkErr -71 /*couldn't find a data mark header*/
  18599. æC 
  18600.  
  18601. æKY badDCksum
  18602. æFc Errors.h
  18603. æT #define
  18604. æD #define badDCksum -72 /*bad data mark checksum*/
  18605. æC 
  18606.  
  18607. æKY badDBtSlp
  18608. æFc Errors.h
  18609. æT #define
  18610. æD #define badDBtSlp -73 /*bad data mark bit slip nibbles*/
  18611. æC 
  18612.  
  18613. æKY wrUnderrun
  18614. æFc Errors.h
  18615. æT #define
  18616. æD #define wrUnderrun -74 /*write underrun occurred*/
  18617. æC 
  18618.  
  18619. æKY cantStepErr
  18620. æFc Errors.h
  18621. æT #define
  18622. æD #define cantStepErr -75 /*step handshake failed*/
  18623. æC 
  18624.  
  18625. æKY tk0BadErr
  18626. æFc Errors.h
  18627. æT #define
  18628. æD #define tk0BadErr -76 /*track 0 detect doesn't change*/
  18629. æC 
  18630.  
  18631. æKY initIWMErr
  18632. æFc Errors.h
  18633. æT #define
  18634. æD #define initIWMErr -77 /*unable to initialize IWM*/
  18635. æC 
  18636.  
  18637. æKY twoSideErr
  18638. æFc Errors.h
  18639. æT #define
  18640. æD #define twoSideErr -78 /*tried to read 2nd side on a 1-sided drive*/
  18641. æC 
  18642.  
  18643. æKY spdAdjErr
  18644. æFc Errors.h
  18645. æT #define
  18646. æD #define spdAdjErr -79 /*unable to correctly adjust disk speed*/
  18647. æC 
  18648.  
  18649. æKY seekErr
  18650. æFc Errors.h
  18651. æT #define
  18652. æD #define seekErr -80 /*track number wrong on address mark*/
  18653. æC 
  18654.  
  18655. æKY sectNFErr
  18656. æFc Errors.h
  18657. æT #define
  18658. æD #define sectNFErr -81 /*sector number never found on a track*/
  18659. æC 
  18660.  
  18661. æKY fmt1Err
  18662. æFc Errors.h
  18663. æT #define
  18664. æD #define fmt1Err -82 /*can't find sector 0 after track format*/
  18665. æC 
  18666.  
  18667. æKY fmt2Err
  18668. æFc Errors.h
  18669. æT #define
  18670. æD #define fmt2Err -83 /*can't get enough sync*/
  18671. æC 
  18672.  
  18673. æKY verErr
  18674. æFc Errors.h
  18675. æT #define
  18676. æD #define verErr -84 /*track failed to verify*/
  18677. æC 
  18678.  
  18679. æKY firstDskErr
  18680. æFc Errors.h
  18681. æT #define
  18682. æD #define firstDskErr -84 /*I/O System Errors*/
  18683. æC 
  18684.  
  18685. æKY clkRdErr
  18686. æFc Errors.h
  18687. æT #define
  18688. æD #define clkRdErr -85 /*unable to read same clock value twice*/
  18689. æC 
  18690.  
  18691. æKY clkWrErr
  18692. æFc Errors.h
  18693. æT #define
  18694. æD #define clkWrErr -86 /*time written did not verify*/
  18695. æC 
  18696.  
  18697. æKY prWrErr
  18698. æFc Errors.h
  18699. æT #define
  18700. æD #define prWrErr -87 /*parameter ram written didn't read-verify*/
  18701. æC 
  18702.  
  18703. æKY prInitErr
  18704. æFc Errors.h
  18705. æT #define
  18706. æD #define prInitErr -88 /*InitUtil found the parameter ram uninitialized*/
  18707. æC 
  18708.  
  18709. æKY rcvrErr
  18710. æFc Errors.h
  18711. æT #define
  18712. æD #define rcvrErr -89 /*SCC receiver error (framing; parity; OR)*/
  18713. æC 
  18714.  
  18715. æKY breakRecd
  18716. æFc Errors.h
  18717. æT #define
  18718. æD #define breakRecd -90 /*Break received (SCC)*/
  18719. æC 
  18720.  
  18721. æKY ddpSktErr
  18722. æFc Errors.h
  18723. æT #define
  18724. æD #define ddpSktErr -91 /*error in soket number*/
  18725. æC 
  18726.  
  18727. æKY ddpLenErr
  18728. æFc Errors.h
  18729. æT #define
  18730. æD #define ddpLenErr -92 /*data length too big*/
  18731. æC 
  18732.  
  18733. æKY noBridgeErr
  18734. æFc Errors.h
  18735. æT #define
  18736. æD #define noBridgeErr -93 /*no network bridge for non-local send*/
  18737. æC 
  18738.  
  18739. æKY lapProtErr
  18740. æFc Errors.h
  18741. æT #define
  18742. æD #define lapProtErr -94 /*error in attaching/detaching protocol*/
  18743. æC 
  18744.  
  18745. æKY excessCollsns
  18746. æFc Errors.h
  18747. æT #define
  18748. æD #define excessCollsns -95 /*excessive collisions on write*/
  18749. æC 
  18750.  
  18751. æKY portInUse
  18752. æFc Errors.h
  18753. æT #define
  18754. æD #define portInUse -97 /*driver Open error code (port is in use)*/
  18755. æC 
  18756.  
  18757. æKY portNotCf
  18758. æFc Errors.h
  18759. æT #define
  18760. æD #define portNotCf -98 /*driver Open error code (parameter RAM not configured for this connection)*/
  18761. æC 
  18762.  
  18763. æKY memROZErr
  18764. æFc Errors.h
  18765. æT #define
  18766. æD #define memROZErr -99 /*hard error in ROZ*/
  18767. æC 
  18768.  
  18769. æKY noScrapErr
  18770. æFc Errors.h
  18771. æT #define
  18772. æD #define noScrapErr -100 /*No scrap exists error*/
  18773. æC 
  18774.  
  18775. æKY noTypeErr
  18776. æFc Errors.h
  18777. æT #define
  18778. æD #define noTypeErr -102 /*No object of that type in scrap*/
  18779. æC 
  18780.  
  18781. æKY memFullErr
  18782. æFc Errors.h
  18783. æT #define
  18784. æD #define memFullErr -108 /*Not enough room in heap zone*/
  18785. æC 
  18786.  
  18787. æKY nilHandleErr
  18788. æFc Errors.h
  18789. æT #define
  18790. æD #define nilHandleErr -109 /*Master Pointer was NIL in HandleZone or other*/
  18791. æC 
  18792.  
  18793. æKY memAdrErr
  18794. æFc Errors.h
  18795. æT #define
  18796. æD #define memAdrErr -110 /*address was odd; or out of range*/
  18797. æC 
  18798.  
  18799. æKY memWZErr
  18800. æFc Errors.h
  18801. æT #define
  18802. æD #define memWZErr -111 /*WhichZone failed (applied to free block)*/
  18803. æC 
  18804.  
  18805. æKY memPurErr
  18806. æFc Errors.h
  18807. æT #define
  18808. æD #define memPurErr -112 /*trying to purge a locked or non-purgeable block*/
  18809. æC 
  18810.  
  18811. æKY memAZErr
  18812. æFc Errors.h
  18813. æT #define
  18814. æD #define memAZErr -113 /*Address in zone check failed*/
  18815. æC 
  18816.  
  18817. æKY memPCErr
  18818. æFc Errors.h
  18819. æT #define
  18820. æD #define memPCErr -114 /*Pointer Check failed*/
  18821. æC 
  18822.  
  18823. æKY memBCErr
  18824. æFc Errors.h
  18825. æT #define
  18826. æD #define memBCErr -115 /*Block Check failed*/
  18827. æC 
  18828.  
  18829. æKY memSCErr
  18830. æFc Errors.h
  18831. æT #define
  18832. æD #define memSCErr -116 /*Size Check failed*/
  18833. æC 
  18834.  
  18835. æKY memLockedErr
  18836. æFc Errors.h
  18837. æT #define
  18838. æD #define memLockedErr -117 /*trying to move a locked block (MoveHHi)*/
  18839. æC 
  18840.  
  18841. æKY dirNFErr
  18842. æFc Errors.h
  18843. æT #define
  18844. æD #define dirNFErr -120 /*Directory not found*/
  18845. æC 
  18846.  
  18847. æKY tmwdoErr
  18848. æFc Errors.h
  18849. æT #define
  18850. æD #define tmwdoErr -121 /*No free WDCB available*/
  18851. æC 
  18852.  
  18853. æKY badMovErr
  18854. æFc Errors.h
  18855. æT #define
  18856. æD #define badMovErr -122 /*Move into offspring error*/
  18857. æC 
  18858.  
  18859. æKY wrgVolTypErr
  18860. æFc Errors.h
  18861. æT #define
  18862. æD #define wrgVolTypErr -123 /*Wrong volume type error [operation not supported for MFS]*/
  18863. æC 
  18864.  
  18865. æKY volGoneErr
  18866. æFc Errors.h
  18867. æT #define
  18868. æD #define volGoneErr -124 /*Server volume has been disconnected.*/
  18869. æC 
  18870.  
  18871. æKY fsDSIntErr
  18872. æFc Errors.h
  18873. æT #define
  18874. æD #define fsDSIntErr -127 /*Internal file system error*/
  18875. æC 
  18876.  
  18877. æKY userCanceledErr
  18878. æFc Errors.h
  18879. æT #define
  18880. æD #define userCanceledErr -128
  18881. æC 
  18882.  
  18883. æKY fidNotFound
  18884. æFc Errors.h
  18885. æT #define
  18886. æD #define fidNotFound -1300 /*no file thread exists.*/
  18887. æC 
  18888.  
  18889. æKY fidExists
  18890. æFc Errors.h
  18891. æT #define
  18892. æD #define fidExists -1301 /*file id already exists*/
  18893. æC 
  18894.  
  18895. æKY NotAFileErr
  18896. æFc Errors.h
  18897. æT #define
  18898. æD #define NotAFileErr -1302 /*directory specified*/
  18899. æC 
  18900.  
  18901. æKY DiffVolErr
  18902. æFc Errors.h
  18903. æT #define
  18904. æD #define DiffVolErr -1303 /*files on different volumes*/
  18905. æC 
  18906.  
  18907. æKY catChangedErr
  18908. æFc Errors.h
  18909. æT #define
  18910. æD #define catChangedErr -1304 /*the catalog has been modified*/
  18911. æC 
  18912.  
  18913. æKY resNotFound
  18914. æFc Errors.h
  18915. æT #define
  18916. æD #define resNotFound -192 /*Resource not found*/
  18917. æC 
  18918.  
  18919. æKY resFNotFound
  18920. æFc Errors.h
  18921. æT #define
  18922. æD #define resFNotFound -193 /*Resource file not found*/
  18923. æC 
  18924.  
  18925. æKY addResFailed
  18926. æFc Errors.h
  18927. æT #define
  18928. æD #define addResFailed -194 /*AddResource failed*/
  18929. æC 
  18930.  
  18931. æKY addRefFailed
  18932. æFc Errors.h
  18933. æT #define
  18934. æD #define addRefFailed -195 /*AddReference failed*/
  18935. æC 
  18936.  
  18937. æKY rmvResFailed
  18938. æFc Errors.h
  18939. æT #define
  18940. æD #define rmvResFailed -196 /*RmveResource failed*/
  18941. æC 
  18942.  
  18943. æKY rmvRefFailed
  18944. æFc Errors.h
  18945. æT #define
  18946. æD #define rmvRefFailed -197 /*RmveReference failed*/
  18947. æC 
  18948.  
  18949. æKY resAttrErr
  18950. æFc Errors.h
  18951. æT #define
  18952. æD #define resAttrErr -198 /*attribute inconsistent with operation*/
  18953. æC 
  18954.  
  18955. æKY mapReadErr
  18956. æFc Errors.h
  18957. æT #define
  18958. æD #define mapReadErr -199 /*map inconsistent with operation*/
  18959. æC 
  18960.  
  18961. æKY editionMgrInitErr
  18962. æFc Errors.h
  18963. æT #define
  18964. æD #define editionMgrInitErr -450 /*edition manager not inited by this app*/
  18965. æC 
  18966.  
  18967. æKY badSectionErr
  18968. æFc Errors.h
  18969. æT #define
  18970. æD #define badSectionErr -451 /*not a valid SectionRecord*/
  18971. æC 
  18972.  
  18973. æKY notRegisteredSectionErr
  18974. æFc Errors.h
  18975. æT #define
  18976. æD #define notRegisteredSectionErr -452 /*not a registered SectionRecord*/
  18977. æC 
  18978.  
  18979. æKY badEditionFileErr
  18980. æFc Errors.h
  18981. æT #define
  18982. æD #define badEditionFileErr -453 /*edition file is corrupt*/
  18983. æC 
  18984.  
  18985. æKY badSubPartErr
  18986. æFc Errors.h
  18987. æT #define
  18988. æD #define badSubPartErr -454 /*can not use sub parts in this release*/
  18989. æC 
  18990.  
  18991. æKY multiplePublisherWrn
  18992. æFc Errors.h
  18993. æT #define
  18994. æD #define multiplePublisherWrn -460 /*A Publisher is already registered for that container*/
  18995. æC 
  18996.  
  18997. æKY containerNotFoundWrn
  18998. æFc Errors.h
  18999. æT #define
  19000. æD #define containerNotFoundWrn -461 /*could not find editionContainer at this time*/
  19001. æC 
  19002.  
  19003. æKY containerAlreadyOpenWrn
  19004. æFc Errors.h
  19005. æT #define
  19006. æD #define containerAlreadyOpenWrn -462 /*container already opened by this section*/
  19007. æC 
  19008.  
  19009. æKY notThePublisherWrn
  19010. æFc Errors.h
  19011. æT #define
  19012. æD #define notThePublisherWrn -463 /*not the first registered publisher for that container*/
  19013. æC 
  19014.  
  19015. æKY userBreak
  19016. æFc Errors.h
  19017. æT #define
  19018. æD #define userBreak -490 /*user debugger break*/
  19019. æC 
  19020.  
  19021. æKY strUserBreak
  19022. æFc Errors.h
  19023. æT #define
  19024. æD #define strUserBreak -491 /*user debugger break; display string on stack*/
  19025. æC 
  19026.  
  19027. æKY exUserBreak
  19028. æFc Errors.h
  19029. æT #define
  19030. æD #define exUserBreak -492 /*user debugger break; execute debugger commands on stack*/
  19031. æC 
  19032.  
  19033. æKY nbpBuffOvr
  19034. æFc Errors.h
  19035. æT #define
  19036. æD #define nbpBuffOvr -1024 /*Buffer overflow in LookupName*/
  19037. æC 
  19038.  
  19039. æKY nbpNoConfirm
  19040. æFc Errors.h
  19041. æT #define
  19042. æD #define nbpNoConfirm -1025
  19043. æC 
  19044.  
  19045. æKY nbpConfDiff
  19046. æFc Errors.h
  19047. æT #define
  19048. æD #define nbpConfDiff -1026 /*Name confirmed at different socket*/
  19049. æC 
  19050.  
  19051. æKY nbpDuplicate
  19052. æFc Errors.h
  19053. æT #define
  19054. æD #define nbpDuplicate -1027 /*Duplicate name exists already*/
  19055. æC 
  19056.  
  19057. æKY nbpNotFound
  19058. æFc Errors.h
  19059. æT #define
  19060. æD #define nbpNotFound -1028 /*Name not found on remove*/
  19061. æC 
  19062.  
  19063. æKY nbpNISErr
  19064. æFc Errors.h
  19065. æT #define
  19066. æD #define nbpNISErr -1029 /*Error trying to open the NIS*/
  19067. æC 
  19068.  
  19069. æKY aspBadVersNum
  19070. æFc Errors.h
  19071. æT #define
  19072. æD #define aspBadVersNum -1066 /*Server cannot support this ASP version*/
  19073. æC 
  19074.  
  19075. æKY aspBufTooSmall
  19076. æFc Errors.h
  19077. æT #define
  19078. æD #define aspBufTooSmall -1067 /*Buffer too small*/
  19079. æC 
  19080.  
  19081. æKY aspNoMoreSess
  19082. æFc Errors.h
  19083. æT #define
  19084. æD #define aspNoMoreSess -1068 /*No more sessions on server*/
  19085. æC 
  19086.  
  19087. æKY aspNoServers
  19088. æFc Errors.h
  19089. æT #define
  19090. æD #define aspNoServers -1069 /*No servers at that address*/
  19091. æC 
  19092.  
  19093. æKY aspParamErr
  19094. æFc Errors.h
  19095. æT #define
  19096. æD #define aspParamErr -1070 /*Parameter error*/
  19097. æC 
  19098.  
  19099. æKY aspServerBusy
  19100. æFc Errors.h
  19101. æT #define
  19102. æD #define aspServerBusy -1071 /*Server cannot open another session*/
  19103. æC 
  19104.  
  19105. æKY aspSessClosed
  19106. æFc Errors.h
  19107. æT #define
  19108. æD #define aspSessClosed -1072 /*Session closed*/
  19109. æC 
  19110.  
  19111. æKY aspSizeErr
  19112. æFc Errors.h
  19113. æT #define
  19114. æD #define aspSizeErr -1073 /*Command block too big*/
  19115. æC 
  19116.  
  19117. æKY aspTooMany
  19118. æFc Errors.h
  19119. æT #define
  19120. æD #define aspTooMany -1074 /*Too many clients (server error)*/
  19121. æC 
  19122.  
  19123. æKY aspNoAck
  19124. æFc Errors.h
  19125. æT #define
  19126. æD #define aspNoAck -1075 /*No ack on attention request (server err)*/
  19127. æC 
  19128.  
  19129. æKY reqFailed
  19130. æFc Errors.h
  19131. æT #define
  19132. æD #define reqFailed -1096
  19133. æC 
  19134.  
  19135. æKY tooManyReqs
  19136. æFc Errors.h
  19137. æT #define
  19138. æD #define tooManyReqs -1097
  19139. æC 
  19140.  
  19141. æKY tooManySkts
  19142. æFc Errors.h
  19143. æT #define
  19144. æD #define tooManySkts -1098
  19145. æC 
  19146.  
  19147. æKY badATPSkt
  19148. æFc Errors.h
  19149. æT #define
  19150. æD #define badATPSkt -1099
  19151. æC 
  19152.  
  19153. æKY badBuffNum
  19154. æFc Errors.h
  19155. æT #define
  19156. æD #define badBuffNum -1100
  19157. æC 
  19158.  
  19159. æKY noRelErr
  19160. æFc Errors.h
  19161. æT #define
  19162. æD #define noRelErr -1101
  19163. æC 
  19164.  
  19165. æKY cbNotFound
  19166. æFc Errors.h
  19167. æT #define
  19168. æD #define cbNotFound -1102
  19169. æC 
  19170.  
  19171. æKY noSendResp
  19172. æFc Errors.h
  19173. æT #define
  19174. æD #define noSendResp -1103
  19175. æC 
  19176.  
  19177. æKY noDataArea
  19178. æFc Errors.h
  19179. æT #define
  19180. æD #define noDataArea -1104
  19181. æC 
  19182.  
  19183. æKY reqAborted
  19184. æFc Errors.h
  19185. æT #define
  19186. æD #define reqAborted -1105
  19187. æC 
  19188.  
  19189. æKY buf2SmallErr
  19190. æFc Errors.h
  19191. æT #define
  19192. æD #define buf2SmallErr -3101
  19193. æC 
  19194.  
  19195. æKY noMPPErr
  19196. æFc Errors.h
  19197. æT #define
  19198. æD #define noMPPErr -3102
  19199. æC 
  19200.  
  19201. æKY ckSumErr
  19202. æFc Errors.h
  19203. æT #define
  19204. æD #define ckSumErr -3103
  19205. æC 
  19206.  
  19207. æKY extractErr
  19208. æFc Errors.h
  19209. æT #define
  19210. æD #define extractErr -3104
  19211. æC 
  19212.  
  19213. æKY readQErr
  19214. æFc Errors.h
  19215. æT #define
  19216. æD #define readQErr -3105
  19217. æC 
  19218.  
  19219. æKY atpLenErr
  19220. æFc Errors.h
  19221. æT #define
  19222. æD #define atpLenErr -3106
  19223. æC 
  19224.  
  19225. æKY atpBadRsp
  19226. æFc Errors.h
  19227. æT #define
  19228. æD #define atpBadRsp -3107
  19229. æC 
  19230.  
  19231. æKY recNotFnd
  19232. æFc Errors.h
  19233. æT #define
  19234. æD #define recNotFnd -3108
  19235. æC 
  19236.  
  19237. æKY sktClosedErr
  19238. æFc Errors.h
  19239. æT #define
  19240. æD #define sktClosedErr -3109
  19241. æC 
  19242.  
  19243. æKY afpAccessDenied
  19244. æFc Errors.h
  19245. æT #define
  19246. æD #define afpAccessDenied -5000
  19247. æC 
  19248.  
  19249. æKY afpAuthContinue
  19250. æFc Errors.h
  19251. æT #define
  19252. æD #define afpAuthContinue -5001
  19253. æC 
  19254.  
  19255. æKY afpBadUAM
  19256. æFc Errors.h
  19257. æT #define
  19258. æD #define afpBadUAM -5002
  19259. æC 
  19260.  
  19261. æKY afpBadVersNum
  19262. æFc Errors.h
  19263. æT #define
  19264. æD #define afpBadVersNum -5003
  19265. æC 
  19266.  
  19267. æKY afpBitmapErr
  19268. æFc Errors.h
  19269. æT #define
  19270. æD #define afpBitmapErr -5004
  19271. æC 
  19272.  
  19273. æKY afpCantMove
  19274. æFc Errors.h
  19275. æT #define
  19276. æD #define afpCantMove -5005
  19277. æC 
  19278.  
  19279. æKY afpDenyConflict
  19280. æFc Errors.h
  19281. æT #define
  19282. æD #define afpDenyConflict -5006
  19283. æC 
  19284.  
  19285. æKY afpDirNotEmpty
  19286. æFc Errors.h
  19287. æT #define
  19288. æD #define afpDirNotEmpty -5007
  19289. æC 
  19290.  
  19291. æKY afpDiskFull
  19292. æFc Errors.h
  19293. æT #define
  19294. æD #define afpDiskFull -5008
  19295. æC 
  19296.  
  19297. æKY afpEofError
  19298. æFc Errors.h
  19299. æT #define
  19300. æD #define afpEofError -5009
  19301. æC 
  19302.  
  19303. æKY afpFileBusy
  19304. æFc Errors.h
  19305. æT #define
  19306. æD #define afpFileBusy -5010
  19307. æC 
  19308.  
  19309. æKY afpFlatVol
  19310. æFc Errors.h
  19311. æT #define
  19312. æD #define afpFlatVol -5011
  19313. æC 
  19314.  
  19315. æKY afpItemNotFound
  19316. æFc Errors.h
  19317. æT #define
  19318. æD #define afpItemNotFound -5012
  19319. æC 
  19320.  
  19321. æKY memROZWarn
  19322. æFc Errors.h
  19323. æT #define
  19324. æD #define memROZWarn -99 /*soft error in ROZ*/
  19325. æC 
  19326.  
  19327. æKY afpLockErr
  19328. æFc Errors.h
  19329. æT #define
  19330. æD #define afpLockErr -5013
  19331. æC 
  19332.  
  19333. æKY afpMiscErr
  19334. æFc Errors.h
  19335. æT #define
  19336. æD #define afpMiscErr -5014
  19337. æC 
  19338.  
  19339. æKY afpNoMoreLocks
  19340. æFc Errors.h
  19341. æT #define
  19342. æD #define afpNoMoreLocks -5015
  19343. æC 
  19344.  
  19345. æKY afpNoServer
  19346. æFc Errors.h
  19347. æT #define
  19348. æD #define afpNoServer -5016
  19349. æC 
  19350.  
  19351. æKY afpObjectExists
  19352. æFc Errors.h
  19353. æT #define
  19354. æD #define afpObjectExists -5017
  19355. æC 
  19356.  
  19357. æKY afpObjectNotFound
  19358. æFc Errors.h
  19359. æT #define
  19360. æD #define afpObjectNotFound -5018
  19361. æC 
  19362.  
  19363. æKY afpParmErr
  19364. æFc Errors.h
  19365. æT #define
  19366. æD #define afpParmErr -5019
  19367. æC 
  19368.  
  19369. æKY afpRangeNotLocked
  19370. æFc Errors.h
  19371. æT #define
  19372. æD #define afpRangeNotLocked -5020
  19373. æC 
  19374.  
  19375. æKY afpRangeOverlap
  19376. æFc Errors.h
  19377. æT #define
  19378. æD #define afpRangeOverlap -5021
  19379. æC 
  19380.  
  19381. æKY afpSessClosed
  19382. æFc Errors.h
  19383. æT #define
  19384. æD #define afpSessClosed -5022
  19385. æC 
  19386.  
  19387. æKY afpUserNotAuth
  19388. æFc Errors.h
  19389. æT #define
  19390. æD #define afpUserNotAuth -5023
  19391. æC 
  19392.  
  19393. æKY afpCallNotSupported
  19394. æFc Errors.h
  19395. æT #define
  19396. æD #define afpCallNotSupported -5024
  19397. æC 
  19398.  
  19399. æKY afpObjectTypeErr
  19400. æFc Errors.h
  19401. æT #define
  19402. æD #define afpObjectTypeErr -5025
  19403. æC 
  19404.  
  19405. æKY afpTooManyFilesOpen
  19406. æFc Errors.h
  19407. æT #define
  19408. æD #define afpTooManyFilesOpen -5026
  19409. æC 
  19410.  
  19411. æKY afpServerGoingDown
  19412. æFc Errors.h
  19413. æT #define
  19414. æD #define afpServerGoingDown -5027
  19415. æC 
  19416.  
  19417. æKY afpCantRename
  19418. æFc Errors.h
  19419. æT #define
  19420. æD #define afpCantRename -5028
  19421. æC 
  19422.  
  19423. æKY afpDirNotFound
  19424. æFc Errors.h
  19425. æT #define
  19426. æD #define afpDirNotFound -5029
  19427. æC 
  19428.  
  19429. æKY afpIconTypeError
  19430. æFc Errors.h
  19431. æT #define
  19432. æD #define afpIconTypeError -5030
  19433. æC 
  19434.  
  19435. æKY afpVolLocked
  19436. æFc Errors.h
  19437. æT #define
  19438. æD #define afpVolLocked -5031 /*Volume is Read-Only*/
  19439. æC 
  19440.  
  19441. æKY afpObjectLocked
  19442. æFc Errors.h
  19443. æT #define
  19444. æD #define afpObjectLocked -5032 /*Object is M/R/D/W inhibited*/
  19445. æC 
  19446.  
  19447. æKY envNotPresent
  19448. æFc Errors.h
  19449. æT #define
  19450. æD #define envNotPresent -5500 /*returned by glue.*/
  19451. æC 
  19452.  
  19453. æKY envBadVers
  19454. æFc Errors.h
  19455. æT #define
  19456. æD #define envBadVers -5501 /*Version non-positive*/
  19457. æC 
  19458.  
  19459. æKY envVersTooBig
  19460. æFc Errors.h
  19461. æT #define
  19462. æD #define envVersTooBig -5502 /*Version bigger than call can handle*/
  19463. æC 
  19464.  
  19465. æKY evtNotEnb
  19466. æFc Errors.h
  19467. æT #define
  19468. æD #define evtNotEnb 1 /*event not enabled at PostEvent*/
  19469. æC 
  19470.  
  19471. æKY dsSysErr
  19472. æFc Errors.h
  19473. æT #define
  19474. æD #define dsSysErr 32767 /*general system error*/
  19475. æC 
  19476.  
  19477. æKY dsBusError
  19478. æFc Errors.h
  19479. æT #define
  19480. æD #define dsBusError 1 /*bus error */
  19481. æC 
  19482.  
  19483. æKY dsAddressErr
  19484. æFc Errors.h
  19485. æT #define
  19486. æD #define dsAddressErr 2 /*address error*/
  19487. æC 
  19488.  
  19489. æKY dsIllInstErr
  19490. æFc Errors.h
  19491. æT #define
  19492. æD #define dsIllInstErr 3 /*illegal instruction error*/
  19493. æC 
  19494.  
  19495. æKY dsZeroDivErr
  19496. æFc Errors.h
  19497. æT #define
  19498. æD #define dsZeroDivErr 4 /*zero divide error*/
  19499. æC 
  19500.  
  19501. æKY dsChkErr
  19502. æFc Errors.h
  19503. æT #define
  19504. æD #define dsChkErr 5 /*check trap error*/
  19505. æC 
  19506.  
  19507. æKY dsOvflowErr
  19508. æFc Errors.h
  19509. æT #define
  19510. æD #define dsOvflowErr 6 /*overflow trap error*/
  19511. æC 
  19512.  
  19513. æKY dsPrivErr
  19514. æFc Errors.h
  19515. æT #define
  19516. æD #define dsPrivErr 7 /*privilege violation error*/
  19517. æC 
  19518.  
  19519. æKY dsTraceErr
  19520. æFc Errors.h
  19521. æT #define
  19522. æD #define dsTraceErr 8 /*trace mode error*/
  19523. æC 
  19524.  
  19525. æKY dsLineAErr
  19526. æFc Errors.h
  19527. æT #define
  19528. æD #define dsLineAErr 9 /*line 1010 trap error*/
  19529. æC 
  19530.  
  19531. æKY dsLineFErr
  19532. æFc Errors.h
  19533. æT #define
  19534. æD #define dsLineFErr 10 /*line 1111 trap error*/
  19535. æC 
  19536.  
  19537. æKY dsMiscErr
  19538. æFc Errors.h
  19539. æT #define
  19540. æD #define dsMiscErr 11 /*miscellaneous hardware exception error*/
  19541. æC 
  19542.  
  19543. æKY dsCoreErr
  19544. æFc Errors.h
  19545. æT #define
  19546. æD #define dsCoreErr 12 /*unimplemented core routine error*/
  19547. æC 
  19548.  
  19549. æKY dsIrqErr
  19550. æFc Errors.h
  19551. æT #define
  19552. æD #define dsIrqErr 13 /*uninstalled interrupt error*/
  19553. æC 
  19554.  
  19555. æKY dsIOCoreErr
  19556. æFc Errors.h
  19557. æT #define
  19558. æD #define dsIOCoreErr 14 /*IO Core Error*/
  19559. æC 
  19560.  
  19561. æKY dsLoadErr
  19562. æFc Errors.h
  19563. æT #define
  19564. æD #define dsLoadErr 15 /*Segment Loader Error*/
  19565. æC 
  19566.  
  19567. æKY dsFPErr
  19568. æFc Errors.h
  19569. æT #define
  19570. æD #define dsFPErr 16 /*Floating point error*/
  19571. æC 
  19572.  
  19573. æKY dsNoPackErr
  19574. æFc Errors.h
  19575. æT #define
  19576. æD #define dsNoPackErr 17 /*package 0 not present*/
  19577. æC 
  19578.  
  19579. æKY dsNoPk1
  19580. æFc Errors.h
  19581. æT #define
  19582. æD #define dsNoPk1 18 /*package 1 not present*/
  19583. æC 
  19584.  
  19585. æKY dsNoPk2
  19586. æFc Errors.h
  19587. æT #define
  19588. æD #define dsNoPk2 19 /*package 2 not present*/
  19589. æC 
  19590.  
  19591. æKY dsNoPk3
  19592. æFc Errors.h
  19593. æT #define
  19594. æD #define dsNoPk3 20 /*package 3 not present*/
  19595. æC 
  19596.  
  19597. æKY dsNoPk4
  19598. æFc Errors.h
  19599. æT #define
  19600. æD #define dsNoPk4 21 /*package 4 not present*/
  19601. æC 
  19602.  
  19603. æKY dsNoPk5
  19604. æFc Errors.h
  19605. æT #define
  19606. æD #define dsNoPk5 22 /*package 5 not present*/
  19607. æC 
  19608.  
  19609. æKY dsNoPk6
  19610. æFc Errors.h
  19611. æT #define
  19612. æD #define dsNoPk6 23 /*package 6 not present*/
  19613. æC 
  19614.  
  19615. æKY dsNoPk7
  19616. æFc Errors.h
  19617. æT #define
  19618. æD #define dsNoPk7 24 /*package 7 not present*/
  19619. æC 
  19620.  
  19621. æKY dsMemFullErr
  19622. æFc Errors.h
  19623. æT #define
  19624. æD #define dsMemFullErr 25 /*out of memory!*/
  19625. æC 
  19626.  
  19627. æKY dsBadLaunch
  19628. æFc Errors.h
  19629. æT #define
  19630. æD #define dsBadLaunch 26 /*can't launch file*/
  19631. æC 
  19632.  
  19633. æKY dsFSErr
  19634. æFc Errors.h
  19635. æT #define
  19636. æD #define dsFSErr 27 /*file system map has been trashed*/
  19637. æC 
  19638.  
  19639. æKY dsStknHeap
  19640. æFc Errors.h
  19641. æT #define
  19642. æD #define dsStknHeap 28 /*stack has moved into application heap*/
  19643. æC 
  19644.  
  19645. æKY dsReinsert
  19646. æFc Errors.h
  19647. æT #define
  19648. æD #define dsReinsert 30 /*request user to reinsert off-line volume*/
  19649. æC 
  19650.  
  19651. æKY dsNotThe1
  19652. æFc Errors.h
  19653. æT #define
  19654. æD #define dsNotThe1 31 /*not the disk I wanted*/
  19655. æC 
  19656.  
  19657. æKY negZcbFreeErr
  19658. æFc Errors.h
  19659. æT #define
  19660. æD #define negZcbFreeErr 33 /*ZcbFree has gone negative*/
  19661. æC 
  19662.  
  19663. æKY dsGreeting
  19664. æFc Errors.h
  19665. æT #define
  19666. æD #define dsGreeting 40 /*welcome to Macintosh greeting*/
  19667. æC 
  19668.  
  19669. æKY dsFinderErr
  19670. æFc Errors.h
  19671. æT #define
  19672. æD #define dsFinderErr 41 /*can't load the Finder error*/
  19673. æC 
  19674.  
  19675. æKY shutDownAlert
  19676. æFc Errors.h
  19677. æT #define
  19678. æD #define shutDownAlert 42 /*handled like a shutdown error*/
  19679. æC 
  19680.  
  19681. æKY menuPrgErr
  19682. æFc Errors.h
  19683. æT #define
  19684. æD #define menuPrgErr 84 /*happens when a menu is purged*/
  19685. æC 
  19686.  
  19687. æKY swOverrunErr
  19688. æFc Errors.h
  19689. æT #define
  19690. æD #define swOverrunErr 1 /*serial driver error masks*/
  19691. æC 
  19692.  
  19693. æKY parityErr
  19694. æFc Errors.h
  19695. æT #define
  19696. æD #define parityErr 16 /*serial driver error masks*/
  19697. æC 
  19698.  
  19699. æKY hwOverrunErr
  19700. æFc Errors.h
  19701. æT #define
  19702. æD #define hwOverrunErr 32 /*serial driver error masks*/
  19703. æC 
  19704.  
  19705. æKY framingErr
  19706. æFc Errors.h
  19707. æT #define
  19708. æD #define framingErr 64 /*serial driver error masks*/
  19709. æC 
  19710.  
  19711. æKY cMatchErr
  19712. æFc Errors.h
  19713. æT #define
  19714. æD #define cMatchErr -150 /*Color2Index failed to find an index*/
  19715. æC 
  19716.  
  19717. æKY cTempMemErr
  19718. æFc Errors.h
  19719. æT #define
  19720. æD #define cTempMemErr -151 /*failed to allocate memory for temporary structures*/
  19721. æC 
  19722.  
  19723. æKY cNoMemErr
  19724. æFc Errors.h
  19725. æT #define
  19726. æD #define cNoMemErr -152 /*failed to allocate memory for structure*/
  19727. æC 
  19728.  
  19729. æKY cRangeErr
  19730. æFc Errors.h
  19731. æT #define
  19732. æD #define cRangeErr -153 /*range error on colorTable request*/
  19733. æC 
  19734.  
  19735. æKY cProtectErr
  19736. æFc Errors.h
  19737. æT #define
  19738. æD #define cProtectErr -154 /*colorTable entry protection violation*/
  19739. æC 
  19740.  
  19741. æKY cDevErr
  19742. æFc Errors.h
  19743. æT #define
  19744. æD #define cDevErr -155 /*invalid type of graphics device*/
  19745. æC 
  19746.  
  19747. æKY cResErr
  19748. æFc Errors.h
  19749. æT #define
  19750. æD #define cResErr -156 /*invalid resolution for MakeITable*/
  19751. æC 
  19752.  
  19753. æKY unitTblFullErr
  19754. æFc Errors.h
  19755. æT #define
  19756. æD #define unitTblFullErr -29 /*unit table has no more entries*/
  19757. æC 
  19758.  
  19759. æKY dceExtErr
  19760. æFc Errors.h
  19761. æT #define
  19762. æD #define dceExtErr -30 /*dce extension error*/
  19763. æC 
  19764.  
  19765. æKY dsBadSlotInt
  19766. æFc Errors.h
  19767. æT #define
  19768. æD #define dsBadSlotInt 51 /*unserviceable slot interrupt*/
  19769. æC 
  19770.  
  19771. æKY dsBadSANEopcode
  19772. æFc Errors.h
  19773. æT #define
  19774. æD #define dsBadSANEopcode 81 /*bad opcode given to SANE Pack4*/
  19775. æC 
  19776.  
  19777. æKY dsNoPatch
  19778. æFc Errors.h
  19779. æT #define
  19780. æD #define dsNoPatch 98 /*Can't patch for particular Model Mac*/
  19781. æC 
  19782.  
  19783. æKY dsBadPatch
  19784. æFc Errors.h
  19785. æT #define
  19786. æD #define dsBadPatch 99 /*Can't load patch resource*/
  19787. æC 
  19788.  
  19789. æKY updPixMemErr
  19790. æFc Errors.h
  19791. æT #define
  19792. æD #define updPixMemErr -125 /*insufficient memory to update a pixmap*/
  19793. æC /*insuffiFc Errors.h
  19794. CIent memory to update a pixmap*/
  19795.  
  19796. æKY mBarNFnd
  19797. æFc Errors.h
  19798. æT #define
  19799. æD #define mBarNFnd -126 /*system error code for MBDF not found*/
  19800. æC 
  19801.  
  19802. æKY hMenuFindErr
  19803. æFc Errors.h
  19804. æT #define
  19805. æD #define hMenuFindErr -127 /*could not find HMenu's parent in MenuKey*/
  19806. æC 
  19807.  
  19808. æKY noHardware
  19809. æFc Errors.h
  19810. æT #define
  19811. æD #define noHardware -200 /*Sound Manager Error Returns*/
  19812. æC 
  19813.  
  19814. æKY notEnoughHardware
  19815. æFc Errors.h
  19816. æT #define
  19817. æD #define notEnoughHardware -201 /*Sound Manager Error Returns*/
  19818. æC 
  19819.  
  19820. æKY queueFull
  19821. æFc Errors.h
  19822. æT #define
  19823. æD #define queueFull -203 /*Sound Manager Error Returns*/
  19824. æC 
  19825.  
  19826. æKY resProblem
  19827. æFc Errors.h
  19828. æT #define
  19829. æD #define resProblem -204 /*Sound Manager Error Returns*/
  19830. æC 
  19831.  
  19832. æKY badChannel
  19833. æFc Errors.h
  19834. æT #define
  19835. æD #define badChannel -205 /*Sound Manager Error Returns*/
  19836. æC 
  19837.  
  19838. æKY badFormat
  19839. æFc Errors.h
  19840. æT #define
  19841. æD #define badFormat -206 /*Sound Manager Error Returns*/
  19842. æC 
  19843.  
  19844. æKY smSDMInitErr
  19845. æFc Errors.h
  19846. æT #define
  19847. æD #define smSDMInitErr -290 /*Error; SDM could not be initialized.*/
  19848. æC 
  19849.  
  19850. æKY smSRTInitErr
  19851. æFc Errors.h
  19852. æT #define
  19853. æD #define smSRTInitErr -291 /*Error; Slot Resource Table could not be initialized.*/
  19854. æC 
  19855.  
  19856. æKY smPRAMInitErr
  19857. æFc Errors.h
  19858. æT #define
  19859. æD #define smPRAMInitErr -292 /*Error; Slot Resource Table could not be initialized.*/
  19860. æC 
  19861.  
  19862. æKY smPriInitErr
  19863. æFc Errors.h
  19864. æT #define
  19865. æD #define smPriInitErr -293 /*Error; Cards could not be initialized.*/
  19866. æC 
  19867.  
  19868. æKY nmTypErr
  19869. æFc Errors.h
  19870. æT #define
  19871. æD #define nmTypErr -299
  19872. æC 
  19873.  
  19874. æKY smEmptySlot
  19875. æFc Errors.h
  19876. æT #define
  19877. æD #define smEmptySlot -300 /*No card in slot*/
  19878. æC 
  19879.  
  19880. æKY smCRCFail
  19881. æFc Errors.h
  19882. æT #define
  19883. æD #define smCRCFail -301 /*CRC check failed for declaration data*/
  19884. æC 
  19885.  
  19886. æKY smFormatErr
  19887. æFc Errors.h
  19888. æT #define
  19889. æD #define smFormatErr -302 /*FHeader Format is not Apple's*/
  19890. æC 
  19891.  
  19892. æKY smRevisionErr
  19893. æFc Errors.h
  19894. æT #define
  19895. æD #define smRevisionErr -303 /*Wrong revison level*/
  19896. æC 
  19897.  
  19898. æKY smNoDir
  19899. æFc Errors.h
  19900. æT #define
  19901. æD #define smNoDir -304 /*Directory offset is Nil */
  19902. æC 
  19903.  
  19904. æKY smLWTstBad
  19905. æFc Errors.h
  19906. æT #define
  19907. æD #define smLWTstBad -305 /*Long Word test field <> $5A932BC7.*/
  19908. æC 
  19909.  
  19910. æKY smNosInfoArray
  19911. æFc Errors.h
  19912. æT #define
  19913. æD #define smNosInfoArray -306 /*No sInfoArray. Memory Mgr error.*/
  19914. æC 
  19915.  
  19916. æKY smResrvErr
  19917. æFc Errors.h
  19918. æT #define
  19919. æD #define smResrvErr -307 /*Fatal reserved error. Resreved field <> 0.*/
  19920. æC 
  19921.  
  19922. æKY smUnExBusErr
  19923. æFc Errors.h
  19924. æT #define
  19925. æD #define smUnExBusErr -308 /*Unexpected BusError*/
  19926. æC 
  19927.  
  19928. æKY smBLFieldBad
  19929. æFc Errors.h
  19930. æT #define
  19931. æD #define smBLFieldBad -309 /*ByteLanes field was bad.*/
  19932. æC 
  19933.  
  19934. æKY smFHBlockRdErr
  19935. æFc Errors.h
  19936. æT #define
  19937. æD #define smFHBlockRdErr -310 /*Error occured during _sGetFHeader.*/
  19938. æC 
  19939.  
  19940. æKY smDisposePErr
  19941. æFc Errors.h
  19942. æT #define
  19943. æD #define smDisposePErr -312 /*_DisposePointer error*/
  19944. æC 
  19945.  
  19946. æKY smNoBoardsRsrc
  19947. æFc Errors.h
  19948. æT #define
  19949. æD #define smNoBoardsRsrc -313 /*No Board sResource.*/
  19950. æC 
  19951.  
  19952. æKY smGetPRErr
  19953. æFc Errors.h
  19954. æT #define
  19955. æD #define smGetPRErr -314 /*Error occured during _sGetPRAMRec (See SIMStatus).*/
  19956. æC 
  19957.  
  19958. æKY smNoBoardId
  19959. æFc Errors.h
  19960. æT #define
  19961. æD #define smNoBoardId -315 /*No Board Id.*/
  19962. æC 
  19963.  
  19964. æKY smInitStatVErr
  19965. æFc Errors.h
  19966. æT #define
  19967. æD #define smInitStatVErr -316 /*The InitStatusV field was negative after primary or secondary init.*/
  19968. æC 
  19969.  
  19970. æKY smInitTblErr
  19971. æFc Errors.h
  19972. æT #define
  19973. æD #define smInitTblErr -317 /*An error occured while trying to initialize the Slot Resource Table.*/
  19974. æC 
  19975.  
  19976. æKY smNoJmpTbl
  19977. æFc Errors.h
  19978. æT #define
  19979. æD #define smNoJmpTbl -318 /*SDM jump table could not be created.*/
  19980. æC 
  19981.  
  19982. æKY smBadBoardId
  19983. æFc Errors.h
  19984. æT #define
  19985. æD #define smBadBoardId -319 /*BoardId was wrong; re-init the PRAM record.*/
  19986. æC 
  19987.  
  19988. æKY smBusErrTO
  19989. æFc Errors.h
  19990. æT #define
  19991. æD #define smBusErrTO -320 /*BusError time out.*/
  19992. æC 
  19993.  
  19994. æKY smBadRefId
  19995. æFc Errors.h
  19996. æT #define
  19997. æD #define smBadRefId -330 /*Reference Id not found in List*/
  19998. æC 
  19999.  
  20000. æKY smBadsList
  20001. æFc Errors.h
  20002. æT #define
  20003. æD #define smBadsList -331 /*Bad sList: Id1 < Id2 < Id3 ...format is not followed.*/
  20004. æC 
  20005.  
  20006. æKY smReservedErr
  20007. æFc Errors.h
  20008. æT #define
  20009. æD #define smReservedErr -332 /*Reserved field not zero*/
  20010. æC 
  20011.  
  20012. æKY smCodeRevErr
  20013. æFc Errors.h
  20014. æT #define
  20015. æD #define smCodeRevErr -333 /*Code revision is wrong*/
  20016. æC 
  20017.  
  20018. æKY smCPUErr
  20019. æFc Errors.h
  20020. æT #define
  20021. æD #define smCPUErr -334 /*Code revision is wrong*/
  20022. æC 
  20023.  
  20024. æKY smsPointerNil
  20025. æFc Errors.h
  20026. æT #define
  20027. æD #define smsPointerNil -335 /*LPointer is nil From sOffsetData. If this error occurs; check sInfo rec for more information.*/
  20028. æC 
  20029.  
  20030. æKY smNilsBlockErr
  20031. æFc Errors.h
  20032. æT #define
  20033. æD #define smNilsBlockErr -336 /*Nil sBlock error (Dont allocate and try to use a nil sBlock)*/
  20034. æC 
  20035.  
  20036. æKY smSlotOOBErr
  20037. æFc Errors.h
  20038. æT #define
  20039. æD #define smSlotOOBErr -337 /*Slot out of bounds error*/
  20040. æC 
  20041.  
  20042. æKY smSelOOBErr
  20043. æFc Errors.h
  20044. æT #define
  20045. æD #define smSelOOBErr -338 /*Selector out of bounds error*/
  20046. æC 
  20047.  
  20048. æKY smNewPErr
  20049. æFc Errors.h
  20050. æT #define
  20051. æD #define smNewPErr -339 /*_NewPtr error*/
  20052. æC 
  20053.  
  20054. æKY smBlkMoveErr
  20055. æFc Errors.h
  20056. æT #define
  20057. æD #define smBlkMoveErr -340 /*_BlockMove error*/
  20058. æC 
  20059.  
  20060. æKY smCkStatusErr
  20061. æFc Errors.h
  20062. æT #define
  20063. æD #define smCkStatusErr -341 /*Status of slot = fail.*/
  20064. æC 
  20065.  
  20066. æKY smGetDrvrNamErr
  20067. æFc Errors.h
  20068. æT #define
  20069. æD #define smGetDrvrNamErr -342 /*Error occured during _sGetDrvrName.*/
  20070. æC 
  20071.  
  20072. æKY smDisDrvrNamErr
  20073. æFc Errors.h
  20074. æT #define
  20075. æD #define smDisDrvrNamErr -343 /*Error occured during _sDisDrvrName.*/
  20076. æC 
  20077.  
  20078. æKY smNoMoresRsrcs
  20079. æFc Errors.h
  20080. æT #define
  20081. æD #define smNoMoresRsrcs -344 /*No more sResources*/
  20082. æC 
  20083.  
  20084. æKY smsGetDrvrErr
  20085. æFc Errors.h
  20086. æT #define
  20087. æD #define smsGetDrvrErr -345 /*Error occurred during _sGetDriver.*/
  20088. æC 
  20089.  
  20090. æKY smBadsPtrErr
  20091. æFc Errors.h
  20092. æT #define
  20093. æD #define smBadsPtrErr -346 /*Bad pointer was passed to sCalcsPointer*/
  20094. æC 
  20095.  
  20096. æKY smByteLanesErr
  20097. æFc Errors.h
  20098. æT #define
  20099. æD #define smByteLanesErr -347 /*NumByteLanes was determined to be zero.*/
  20100. æC 
  20101.  
  20102. æKY smOffsetErr
  20103. æFc Errors.h
  20104. æT #define
  20105. æD #define smOffsetErr -348 /*Offset was too big (temporary error*/
  20106. æC 
  20107.  
  20108. æKY smNoGoodOpens
  20109. æFc Errors.h
  20110. æT #define
  20111. æD #define smNoGoodOpens -349 /*No opens were successfull in the loop.*/
  20112. æC 
  20113.  
  20114. æKY smSRTOvrFlErr
  20115. æFc Errors.h
  20116. æT #define
  20117. æD #define smSRTOvrFlErr -350 /*SRT over flow.*/
  20118. æC 
  20119.  
  20120. æKY smRecNotFnd
  20121. æFc Errors.h
  20122. æT #define
  20123. æD #define smRecNotFnd -351 /*Record not found in the SRT.*/
  20124. æC 
  20125.  
  20126. æKY slotNumErr
  20127. æFc Errors.h
  20128. æT #define
  20129. æD #define slotNumErr -360 /*invalid slot # error*/
  20130. æC 
  20131.  
  20132. æKY gcrOnMFMErr
  20133. æFc Errors.h
  20134. æT #define
  20135. æD #define gcrOnMFMErr -400 /*gcr format on high density media error*/
  20136. æC 
  20137.  
  20138. æKY rgnTooBigErr
  20139. æFc Errors.h
  20140. æT #define
  20141. æD #define rgnTooBigErr -500
  20142. æC 
  20143.  
  20144. æKY teScrapSizeErr
  20145. æFc Errors.h
  20146. æT #define
  20147. æD #define teScrapSizeErr -501 /*scrap item too big for text edit record*/
  20148. æC 
  20149.  
  20150. æKY hwParamErr
  20151. æFc Errors.h
  20152. æT #define
  20153. æD #define hwParamErr -502 /*bad selector for _HWPriv*/
  20154. æC 
  20155.  
  20156. æKY svTempDisable
  20157. æFc Errors.h
  20158. æT #define
  20159. æD 
  20160. /*  The following errors are for primary or secondary init code.  The errors are logged in the
  20161. vendor status field of the sInfo record.  Normally the vendor error is not Apple's concern,
  20162. but a special error is needed to patch secondary inits.
  20163.  
  20164.  */
  20165.  
  20166. #define svTempDisable -32768 /*Temporarily disable card but run primary init.*/
  20167. æC 
  20168.  
  20169. æKY svDisabled
  20170. æFc Errors.h
  20171. æT #define
  20172. æD #define svDisabled -32640 /*Reserve range -32640 to -32768 for Apple temp disables.*/
  20173. æC 
  20174.  
  20175. æKY siInitSDTblErr
  20176. æFc Errors.h
  20177. æT #define
  20178. æD #define siInitSDTblErr 1 /*slot int dispatch table could not be initialized.*/
  20179. æC 
  20180.  
  20181. æKY siInitVBLQsErr
  20182. æFc Errors.h
  20183. æT #define
  20184. æD #define siInitVBLQsErr 2 /*VBLqueues for all slots could not be initialized.*/
  20185. æC 
  20186.  
  20187. æKY siInitSPTblErr
  20188. æFc Errors.h
  20189. æT #define
  20190. æD #define siInitSPTblErr 3 /*slot priority table could not be initialized.*/
  20191. æC 
  20192.  
  20193. æKY sdmJTInitErr
  20194. æFc Errors.h
  20195. æT #define
  20196. æD #define sdmJTInitErr 10 /*SDM Jump Table could not be initialized.*/
  20197. æC 
  20198.  
  20199. æKY sdmInitErr
  20200. æFc Errors.h
  20201. æT #define
  20202. æD #define sdmInitErr 11 /*SDM could not be initialized.*/
  20203. æC 
  20204.  
  20205. æKY sdmSRTInitErr
  20206. æFc Errors.h
  20207. æT #define
  20208. æD #define sdmSRTInitErr 12 /*Slot Resource Table could not be initialized.*/
  20209. æC 
  20210.  
  20211. æKY sdmPRAMInitErr
  20212. æFc Errors.h
  20213. æT #define
  20214. æD #define sdmPRAMInitErr 13 /*Slot PRAM could not be initialized.*/
  20215. æC 
  20216.  
  20217. æKY sdmPriInitErr
  20218. æFc Errors.h
  20219. æT #define
  20220. æD #define sdmPriInitErr 14 /*Cards could not be initialized.*/
  20221. æC 
  20222.  
  20223. æKY dsMBarNFnd
  20224. æFc Errors.h
  20225. æT #define
  20226. æD #define dsMBarNFnd 85 /*Menu Manager Errors*/
  20227. æC 
  20228.  
  20229. æKY dsHMenuFindErr
  20230. æFc Errors.h
  20231. æT #define
  20232. æD #define dsHMenuFindErr 86 /*Menu Manager Errors*/
  20233. æC 
  20234.  
  20235. æKY MacOSErr
  20236. æFc Errors.h
  20237. æT typedef
  20238. æD extern short MacOSErr;
  20239. æC 
  20240.  
  20241. æKY SysError
  20242. æFc Errors.h
  20243. æT Function
  20244. æD pascal void SysError(short errorCode)
  20245.     = {0x301F,0xA9C9}; 
  20246. æDT SysError((short) errorCode);
  20247. æMM
  20248. æRI II-362, V-572
  20249. æC _____________________________________________________________________________________
  20250.  
  20251. Trap macro  _SysError
  20252. On entry    D0:  errorCode (word)
  20253. On exit     All registers changed
  20254. _____________________________________________________________________________________
  20255. SysError generates a system error with the ID specified by the errorCode 
  20256. parameter.
  20257.  
  20258. It takes the following precise steps:
  20259. 1.  It saves all registers and the stack pointer.
  20260. 2.  It stores the system error ID in a global variable (named DSErrCode).
  20261. 3.  It checks to see whether there's a system error alert table in memory (by 
  20262.     testing whether the global variable DSAlertTab is 0); if there isn't, it draws 
  20263.     the "sad Macintosh" icon.
  20264. 4.  It allocates memory for QuickDraw globals on the stack, initializes 
  20265.     QuickDraw, and initializes a grafPort in which the alert box will be drawn.
  20266. 5.  It checks the system error ID.  If the system error ID is negative, the alert 
  20267.     box isn't redrawn (this is used for system startup alerts, which can display a 
  20268.     sequence of consecutive messages in the same box).  If the system error ID 
  20269.     doesn't correspond to an entry in the system error alert table, the default 
  20270.     alert definition at the start of the table will be used, displaying the message 
  20271.     "Sorry, a system error occurred".
  20272. 6.  It draws an alert box (in the rectangle specified by the global variable 
  20273.     DSAlertRect).
  20274. 7.  If the text definition IDs in the alert definition for this alert aren't 0, it 
  20275.     draws both strings.
  20276. 8.  If the icon definition ID in the alert definition isn't 0, it draws the icon.
  20277. 9.  If the procedure definition ID in the alert definition isn't 0, it invokes the 
  20278.     procedure with the specified ID.
  20279. 10. If the button definition ID in the alert definition is 0, it returns control to 
  20280.     the procedure that called it (this is used during the disk-switch alert to return
  20281.     control to the File Manager after the "Please insert the disk:" message has been 
  20282.     displayed).
  20283. 11. If there's a resume procedure, it increments the button definition ID by 1.
  20284. 12. It draws the buttons.
  20285. 13. It hit-tests the buttons and calls the corresponding procedure code when a 
  20286.     button is pressed.  If there's no procedure code, it returns to the procedure 
  20287.     that called it.
  20288.  
  20289. User Alerts
  20290. _____________
  20291. ID  Explanation
  20292. 1   Bus error:  Invalid memory reference; happens only on a Macintosh XL 
  20293. 2   Address error:  Word or long-word reference made to an odd address
  20294. 3   Illegal instruction:  The MC68000 received an instruction it didn't recognize.
  20295. 4   Zero divide:  Signed Divide (DIVS) or Unsigned Divide (DIVU) instruction 
  20296.                   with a divisor of 0 was executed.
  20297. 5   Check exception:  Check Register Against Bounds (CHK) instruction was executed 
  20298.                       and failed.  Pascal "value out of range" errors are usually 
  20299.                       reported in this way.
  20300. 6   TrapV exception:  Trap On Overflow (TRAPV) instruction was executed and failed.
  20301. 7   Privilege violation:  Macintosh always runs in supervisor mode; perhaps an 
  20302.                           erroneous Return From Execution (RTE) instruction was 
  20303.                           executed.
  20304. 8   Trace exception:  The trace bit in the status register is set.
  20305. 9   Line 1010 exception:  The 1010 trap dispatcher has failed.
  20306. 10  Line 1111 exception:  Unimplemented instruction
  20307. 11  Miscellaneous exception:  All other MC68000 exceptions
  20308. 12  Unimplemented core routine:  An unimplemented trap number was encountered.
  20309. 13  Spurious interrupt:  The interrupt vector table entry for a particular level 
  20310.                          of interrupt is NIL; usually occurs with level 4, 5, 6, or 7 
  20311.                          interrupts.
  20312. 14  I/O system error:  The File Manager is attempting to dequeue an entry from 
  20313.                        an I/O request queue that has a bad queue type field; perhaps 
  20314.                        the queue entry is unlocked.  Or, the dCtlQHead field was NIL 
  20315.                        during a Fetch or Stash call.  Or, a needed device control 
  20316.                        entry has been purged.
  20317. 15  Segment Loader error:  A GetResource call to read a segment into memory failed.
  20318. 16  Floating point error:  The halt bit in the floating-point environment word was 
  20319.                            set.
  20320. 17-24 Can't load package:  A GetResource call to read a package into memory failed.
  20321. 25  Can't allocate requested memory block in the heap
  20322. 26  Segment Loader error:  A GetResource call to read 'CODE' resource 0 into 
  20323.                            memory failed; usually indicates a nonexecutable file.
  20324. 27  File map destroyed:  A logical block number was found that's greater than 
  20325.                          the number of the last logical block on the volume or less 
  20326.                          than the logical block number of the first allocation block 
  20327.                          on the volume.
  20328. 28  Stack overflow error:  The stack has expanded into the heap.
  20329. 30  "Please insert the disk:" File Manager alert
  20330. 41  The file named "Finder" can't be found on the disk.
  20331. 100 Can't mount system startup volume.  The system couldn't read the system resource 
  20332.                                         file into memory.
  20333. 32767 "Sorry, a system error occurred":  Default alert message 
  20334.  
  20335.  
  20336. æKY Events.h
  20337. æKL Button
  20338. EventAvail
  20339. GetCaretTime
  20340. GetDblTime
  20341. GetKeys
  20342. GetMouse
  20343. GetNextEvent
  20344. StillDown
  20345. TickCount
  20346. WaitMouseUp
  20347. WaitNextEvent
  20348.  
  20349. activateEvt
  20350. activeFlag
  20351. activMask
  20352. adbAddrMask
  20353. alphaLock
  20354. app1Evt
  20355. app1Mask
  20356. app2Evt
  20357. app2Mask
  20358. app3Evt
  20359. app3Mask
  20360. app4Evt
  20361. app4Mask
  20362. autoKey
  20363. autoKeyMask
  20364. btnState
  20365. charCodeMask
  20366. childDiedMessage
  20367. cmdKey
  20368. controlKey
  20369. diskEvt
  20370. diskMask
  20371. driverEvt
  20372. driverMask
  20373. EventRecord
  20374. everyEvent
  20375. keyCodeMask
  20376. keyDown
  20377. keyDownMask
  20378. KeyMap
  20379. keyUp
  20380. keyUpMask
  20381. mDownMask
  20382. mouseDown
  20383. mouseMovedMessage
  20384. mouseUp
  20385. mUpMask
  20386. networkEvt
  20387. networkMask
  20388. nullEvent
  20389. optionKey
  20390. osEvt
  20391. osEvtMessageMask
  20392. shiftKey
  20393. suspendResumeMessage
  20394. updateEvt
  20395. updateMask
  20396.  
  20397. æKY nullEvent
  20398. æFc Events.h
  20399. æT #define
  20400. æD #define nullEvent 0
  20401. æC 
  20402. »Event Code
  20403.  
  20404. The what field of an event record contains an event code identifying the type of the
  20405. event. The event codes are available as predefined constants:
  20406.  
  20407. #define nullEvent     0    /*null*/
  20408. #define mouseDown     1    /*mouse-down*/
  20409. #define mouseUp       2    /*mouse-up*/
  20410. #define keyDown       4    /*key-down*/
  20411. #define keyUp         3    /*key-up*/
  20412. #define autoKey       5    /*auto-key*/
  20413. #define updateEvt     6    /*update*/
  20414. #define diskEvt       7    /*disk-inserted*/
  20415. #define activateEvt   8    /*activate*/
  20416. #define networkEvt   10    /*network*/
  20417. #define driverEvt    11    /*device driver*/
  20418. #define app1Evt      12    /*application-defined*/
  20419. #define app2Evt      13    /*application-defined*/
  20420. #define app3Evt      14    /*application-defined*/
  20421. #define app4Evt      15    /*application-defined*/
  20422.  
  20423. æKY mouseDown
  20424. æFc Events.h
  20425. æT #define
  20426. æD #define mouseDown 1
  20427. æC 
  20428.  
  20429. æKY mouseUp
  20430. æFc Events.h
  20431. æT #define
  20432. æD #define mouseUp 2
  20433. æC 
  20434.  
  20435. æKY keyDown
  20436. æFc Events.h
  20437. æT #define
  20438. æD #define keyDown 3
  20439. æC 
  20440.  
  20441. æKY keyUp
  20442. æFc Events.h
  20443. æT #define
  20444. æD #define keyUp 4
  20445. æC 
  20446.  
  20447. æKY autoKey
  20448. æFc Events.h
  20449. æT #define
  20450. æD #define autoKey 5
  20451. æC 
  20452.  
  20453. æKY updateEvt
  20454. æFc Events.h
  20455. æT #define
  20456. æD #define updateEvt 6
  20457. æC 
  20458.  
  20459. æKY diskEvt
  20460. æFc Events.h
  20461. æT #define
  20462. æD #define diskEvt 7
  20463. æC 
  20464.  
  20465. æKY activateEvt
  20466. æFc Events.h
  20467. æT #define
  20468. æD #define activateEvt 8
  20469. æC 
  20470.  
  20471. æKY networkEvt
  20472. æFc Events.h
  20473. æT #define
  20474. æD #define networkEvt 10
  20475. æC 
  20476.  
  20477. æKY driverEvt
  20478. æFc Events.h
  20479. æT #define
  20480. æD #define driverEvt 11
  20481. æC 
  20482.  
  20483. æKY app1Evt
  20484. æFc Events.h
  20485. æT #define
  20486. æD #define app1Evt 12
  20487. æC 
  20488.  
  20489. æKY app2Evt
  20490. æFc Events.h
  20491. æT #define
  20492. æD #define app2Evt 13
  20493. æC 
  20494.  
  20495. æKY app3Evt
  20496. æFc Events.h
  20497. æT #define
  20498. æD #define app3Evt 14
  20499. æC 
  20500.  
  20501. æKY app4Evt
  20502. æFc Events.h
  20503. æT #define
  20504. æD #define app4Evt 15
  20505. æC 
  20506.  
  20507. æKY osEvt
  20508. æFc Events.h
  20509. æT #define
  20510. æD #define osEvt app4Evt
  20511. æC 
  20512.  
  20513. æKY charCodeMask
  20514. æFc Events.h
  20515. æT #define
  20516. æD #define charCodeMask 0x000000FF
  20517. æC 
  20518.  
  20519. æKY keyCodeMask
  20520. æFc Events.h
  20521. æT #define
  20522. æD #define keyCodeMask 0x0000FF00
  20523. æC 
  20524.  
  20525. æKY adbAddrMask
  20526. æFc Events.h
  20527. æT #define
  20528. æD #define adbAddrMask 0x00FF0000
  20529. æC 
  20530.  
  20531. æKY osEvtMessageMask
  20532. æFc Events.h
  20533. æT #define
  20534. æD #define osEvtMessageMask 0xFF000000
  20535. æC 
  20536.  
  20537. æKY mouseMovedMessage
  20538. æFc Events.h
  20539. æT #define
  20540. æD 
  20541. /* OSEvent Messages */
  20542.  
  20543. #define mouseMovedMessage 0xFA
  20544. æC 
  20545.  
  20546. æKY childDiedMessage
  20547. æFc Events.h
  20548. æT #define
  20549. æD #define childDiedMessage 0xFD
  20550. æC 
  20551.  
  20552. æKY suspendResumeMessage
  20553. æFc Events.h
  20554. æT #define
  20555. æD #define suspendResumeMessage 0x01
  20556. æC 
  20557.  
  20558. æKY mDownMask
  20559. æFc Events.h
  20560. æT #define
  20561. æD 
  20562. /* event mask equates */
  20563.  
  20564. #define mDownMask 2
  20565. æC 
  20566. _______________________________________________________________________________
  20567.  
  20568. »EVENT MASKS
  20569. _______________________________________________________________________________
  20570.  
  20571. Some of the Event Manager routines can be restricted to operate on a specific event
  20572. type or group of types; in other words, the specified event types are enabled while
  20573. all others are disabled. For instance, instead of just requesting the next available
  20574. event, you can specifically ask for the next keyboard event.
  20575.  
  20576. You specify which event types a particular Event Manager call applies to by supplying
  20577. an event mask as a parameter. This is an integer in which there’s one bit position
  20578. for each event type, as shown in Figure 8. The bit position representing a given type
  20579. corresponds to the event code for that type—for example, update events (event code 6)
  20580. are specified by bit 6 of the mask. A 1 in bit 6 means that this Event Manager call
  20581. applies to update events; a 0 means that it doesn’t.
  20582.  
  20583. •••Refer to Figure 8.•••
  20584.  
  20585. Figure 8–Event Mask
  20586.  
  20587. Masks for each individual event type are available as predefined constants:
  20588.  
  20589. #define mDownMask    2       /*mouse-down*/
  20590. #define mUpMask      4       /*mouse-up*/
  20591. #define keyDownMask  8       /*key-down*/
  20592. #define keyUpMask    16      /*key-up*/
  20593. #define autoKeyMask  32      /*auto-key*/
  20594. #define updateMask   64      /*update*/
  20595. #define diskMask     128     /*disk-inserted*/
  20596. #define activMask    256     /*activate*/
  20597. #define networkMask  1024    /*network*/
  20598. #define driverMask   2048    /*device driver*/
  20599. #define app1Mask     4096    /*application-defined*/
  20600. #define app2Mask     8192    /*application-defined*/
  20601. #define app3Mask     16384   /*application-defined*/
  20602. #define app4Mask     -32768  /*application-defined*/
  20603.  
  20604. Note:  Null events can’t be disabled; a null event will always be reported
  20605.        when none of the enabled types of events are available.
  20606.  
  20607. The following predefined mask designates all event types:
  20608.  
  20609. CONST    everyEvent    = -1;    {all event types}
  20610.  
  20611. You can form any mask you need by adding or subtracting these mask constants. For
  20612. example, to specify every keyboard event, use
  20613.  
  20614.   keyDownMask + keyUpMask + autoKeyMask
  20615.  
  20616. For every event except an update, use
  20617.  
  20618.   everyEvent - updateMask
  20619.  
  20620. Note:  It’s recommended that you always use the event mask everyEvent unless
  20621.        there’s a specific reason not to.
  20622.  
  20623. There’s also a global system event mask that controls which event types get posted
  20624. into the event queue. Only event types corresponding to bits set in the system event
  20625. mask are posted; all others are ignored. When the system starts up, the system event
  20626. mask is set to post all except key-up event—that is, it’s initialized to
  20627.  
  20628.   everyEvent - keyUpMask
  20629.  
  20630. Note:  Key-up events are meaningless for most applications. Your application
  20631.        will usually want to ignore them; if not, it can set the system event
  20632.        mask with the Operating System Event Manager procedure SetEventMask.
  20633.  
  20634. æKY mUpMask
  20635. æFc Events.h
  20636. æT #define
  20637. æD #define mUpMask 4
  20638. æC 
  20639.  
  20640. æKY keyDownMask
  20641. æFc Events.h
  20642. æT #define
  20643. æD #define keyDownMask 8
  20644. æC 
  20645.  
  20646. æKY keyUpMask
  20647. æFc Events.h
  20648. æT #define
  20649. æD #define keyUpMask 16
  20650. æC 
  20651.  
  20652. æKY autoKeyMask
  20653. æFc Events.h
  20654. æT #define
  20655. æD #define autoKeyMask 32
  20656. æC 
  20657.  
  20658. æKY updateMask
  20659. æFc Events.h
  20660. æT #define
  20661. æD #define updateMask 64
  20662. æC 
  20663.  
  20664. æKY diskMask
  20665. æFc Events.h
  20666. æT #define
  20667. æD #define diskMask 128
  20668. æC 
  20669.  
  20670. æKY activMask
  20671. æFc Events.h
  20672. æT #define
  20673. æD #define activMask 256
  20674. æC 
  20675.  
  20676. æKY networkMask
  20677. æFc Events.h
  20678. æT #define
  20679. æD #define networkMask 1024
  20680. æC 
  20681.  
  20682. æKY driverMask
  20683. æFc Events.h
  20684. æT #define
  20685. æD #define driverMask 2048
  20686. æC 
  20687.  
  20688. æKY app1Mask
  20689. æFc Events.h
  20690. æT #define
  20691. æD #define app1Mask 4096
  20692. æC 
  20693.  
  20694. æKY app2Mask
  20695. æFc Events.h
  20696. æT #define
  20697. æD #define app2Mask 8192
  20698. æC 
  20699.  
  20700. æKY app3Mask
  20701. æFc Events.h
  20702. æT #define
  20703. æD #define app3Mask 16384
  20704. æC 
  20705.  
  20706. æKY app4Mask
  20707. æFc Events.h
  20708. æT #define
  20709. æD #define app4Mask -32768
  20710. æC 
  20711.  
  20712. æKY everyEvent
  20713. æFc Events.h
  20714. æT #define
  20715. æD #define everyEvent -1
  20716. æC 
  20717.  
  20718. æKY activeFlag
  20719. æFc Events.h
  20720. æT #define
  20721. æD 
  20722. /* modifiers */
  20723.  
  20724. #define activeFlag 1 /*bit 0 of modifiers for activate event*/
  20725. æC 
  20726. »Modifier Flags
  20727.  
  20728. As mentioned above, the modifiers field of an event record contains further information
  20729. about activate events and the state of the modifier keys and mouse button at the time
  20730. the event was posted (see Figure 7). You might look at this field to find out, for
  20731. instance, whether the Command key was down when a mouse-down event was posted (which
  20732. in many applications affects the way objects are selected) or when a key-down event
  20733. was posted (which could mean the user is choosing a menu item by typing its keyboard
  20734. equivalent).
  20735.  
  20736. •••Refer to Figure 7.•••
  20737.  
  20738. Figure 7–Modifier Flags
  20739.  
  20740. The following predefined constants are useful as masks for reading the flags in the
  20741. modifiers field:
  20742.  
  20743. #define activeFlag  1     /*set if window being activated*/
  20744. #define btnState    128   /*set if mouse button up*/
  20745. #define cmdKey      256   /*set if Command key down*/
  20746. #define shiftKey    512   /*set if Shift key down*/
  20747. #define alphaLock   1024  /*set if Caps Lock key down*/
  20748. #define optionKey   2048  /*set if Option key down*/
  20749. #define controlKey  4096  /*set if Control key down*/
  20750.  
  20751. The activeFlag bit gives further information about activate events; it’s set if the
  20752. window pointed to by the event message is being activated, or 0 if the window is
  20753. being deactivated. The remaining bits indicate the state of the mouse button and
  20754. modifier keys. Notice that the btnState bit is set if the mouse button is up, whereas
  20755. the bits for the four modifier keys are set if their corresponding keys are down.
  20756.  
  20757. æKY btnState
  20758. æFc Events.h
  20759. æT #define
  20760. æD #define btnState 128 /*Bit 7 of low byte is mouse button state*/
  20761. æC 
  20762.  
  20763. æKY cmdKey
  20764. æFc Events.h
  20765. æT #define
  20766. æD #define cmdKey 256 /*Bit 0*/
  20767. æC 
  20768.  
  20769. æKY shiftKey
  20770. æFc Events.h
  20771. æT #define
  20772. æD #define shiftKey 512 /*Bit 1*/
  20773. æC 
  20774.  
  20775. æKY alphaLock
  20776. æFc Events.h
  20777. æT #define
  20778. æD #define alphaLock 1024 /*Bit 2 */
  20779. æC 
  20780.  
  20781. æKY optionKey
  20782. æFc Events.h
  20783. æT #define
  20784. æD #define optionKey 2048 /*Bit 3 of high byte*/
  20785. æC 
  20786.  
  20787. æKY controlKey
  20788. æFc Events.h
  20789. æT #define
  20790. æD #define controlKey 4096
  20791. æC 
  20792.  
  20793. æKY KeyMap
  20794. æFc Events.h
  20795. æT typedef
  20796. æD typedef long KeyMap[4];
  20797. æC 
  20798.  
  20799. æKY EventRecord
  20800. æFc Events.h
  20801. æT struct
  20802. æD struct EventRecord {
  20803.     short what;
  20804.     long message;
  20805.     long when;
  20806.     Point where;
  20807.     short modifiers;
  20808. };
  20809.  
  20810. typedef struct EventRecord EventRecord;
  20811. æC 
  20812. _______________________________________________________________________________
  20813.  
  20814. »EVENT RECORDS
  20815. _______________________________________________________________________________
  20816.  
  20817. Every event is represented internally by an event record containing all pertinent
  20818. information about that event. The event record includes the following information:
  20819.  
  20820.   •  the type of event
  20821.   •  the time the event was posted (in ticks since system startup)
  20822.   •  the location of the mouse at the time the event was posted (in global
  20823.      coordinates)
  20824.   •  the state of the mouse button and modifier keys at the time the event
  20825.      was posted
  20826.   •  any additional information required for a particular type of event, such
  20827.      as which key the user pressed or which window is being activated
  20828.  
  20829. Every event has an event record containing this information—even null events.
  20830.  
  20831. Event records are defined as follows:
  20832.  
  20833. TYPE  EventRecord = RECORD
  20834.                       what:       INTEGER;  {event code}
  20835.                       message:    LONGINT;  {event message}
  20836.                       when:       LONGINT;  {ticks since startup}
  20837.                       where:      Point;    {mouse location}
  20838.                       modifiers:  INTEGER   {modifier flags}
  20839.                     END;
  20840.  
  20841. The when field contains the number of ticks since the system last started up, and the
  20842. where field gives the location of the mouse, in global coordinates, at the time the
  20843. event was posted. The other three fields are described below.
  20844.  
  20845. _______________________________________________________________________________
  20846.  
  20847. »Event Code
  20848.  
  20849. The what field of an event record contains an event code identifying the type of the
  20850. event. The event codes are available as predefined constants:
  20851.  
  20852. CONST  nullEvent   =  0;    {null}
  20853.        mouseDown   =  1;    {mouse-down}
  20854.        mouseUp     =  2;    {mouse-up}
  20855.        keyDown     =  3;    {key-down}
  20856.        keyUp       =  4;    {key-up}
  20857.        autoKey     =  5;    {auto-key}
  20858.        updateEvt   =  6;    {update}
  20859.        diskEvt     =  7;    {disk-inserted}
  20860.        activateEvt =  8;    {activate}
  20861.        networkEvt  = 10;    {network}
  20862.        driverEvt   = 11;    {device driver}
  20863.        app1Evt     = 12;    {application-defined}
  20864.        app2Evt     = 13;    {application-defined}
  20865.        app3Evt     = 14;    {application-defined}
  20866.        app4Evt     = 15;    {application-defined}
  20867.  
  20868. _______________________________________________________________________________
  20869.  
  20870. »Event Message
  20871.  
  20872. The message field of an event record contains the event message, which conveys additional
  20873. important information about the event. The nature of this information depends on the
  20874. event type, as summarized in the following table and described below.
  20875.  
  20876.   Event type             Event message
  20877.  
  20878.   Keyboard               Character code, key code, and ADB address field
  20879.   Activate, update       Pointer to window
  20880.   Disk-inserted          Drive number in low-order word, File Manager
  20881.                          result code in high-order word
  20882.   Mouse-down,            Undefined
  20883.   mouse-up, null
  20884.   Network                Handle to parameter block
  20885.   Device driver          See chapter describing driver
  20886.   Application-defined    Whatever you wish
  20887.  
  20888. For keyboard events, the low-order byte of the low-order word of the event message
  20889. contains the ASCII character code generated by the key or combination of keys that
  20890. was pressed or released; usually this is all you’ll need.  However, as described in
  20891. the Apple Desktop Bus chapter, the Macintosh II and SE can be connected to multiple
  20892. keyboards.  To identify the origin of keyboard events, the keyboard event message
  20893. contains a new ADB address field.  It now has the structure shown in Figure 2.
  20894.  
  20895. Warning:  The high byte of the event message for keyboard events is reserved
  20896.           for future use, and is not presently guaranteed to be zero.
  20897.  
  20898. The event message for non-keyboard events remains the same as described above.
  20899.  
  20900. •••Refer to Figure 2.•••
  20901.  
  20902. Figure 2–Event Message for Keyboard Events
  20903.  
  20904. The key code in the event message for a keyboard event represents the character key
  20905. that was pressed or released; this value is always the same for any given character
  20906. key, regardless of the modifier keys pressed along with it. Key codes are useful in
  20907. special cases—in a music generator, for example—where you want to treat the keyboard
  20908. as a set of keys unrelated to characters. Figure 3 gives the key codes for all the
  20909. keys on the keyboard and keypad. (Key codes are shown for modifier keys here because
  20910. they’re meaningful in other contexts, as explained later.) Both the U.S. and international
  20911. keyboards are shown; in some cases the codes are quite different (for example, space
  20912. and Enter are reversed).
  20913.  
  20914. Three keyboards are now available as standard equipment with Macintosh computers sold
  20915. in the U.S.  They are
  20916.  
  20917.   •  The Macintosh Plus Keyboard, which includes cursor control keys and an
  20918.      integral keypad.  Its layout and key coding is shown in Figure 4.
  20919.   •  The Macintosh II Keyboard, also shipped with the Macintosh SE, which
  20920.      adds Esc (Escape) and Control keys and is connected to the Apple Desktop
  20921.      Bus.  Its layout and key coding is shown in Figure 5.
  20922.   •  The Apple Extended Keyboard,  which the user may connect to the Apple
  20923.      Desktop Bus of any Macintosh II or Macintosh SE computer.  Its layout
  20924.      and key coding is shown in Figure 6.
  20925.  
  20926. These figures show the virtual key codes for each key; they are the key codes that
  20927. actually appear in keyboard events.  In the case of the Macintosh II and Apple Extended
  20928. Keyboards, however, the hardware produces raw key codes, which may be different.  Raw
  20929. key codes are translated to virtual key codes by the
  20930. 'KMAP' resource in the System Folder.  By modifying the 'KMAP' resource you can
  20931. change the key codes for any keys.  Similarly, you can change the ASCII codes corresponding
  20932. to specific key codes by modifying the 'KCHR' resource in the System Folder.  The
  20933. 'KMAP' and 'KCHR' resources are described in the Resource Manager chapter.
  20934.  
  20935. With both the Macintosh II and the Apple Extended keyboards, the standard 'KMAP'
  20936. resource supplied in the system folder reassigns the following raw key codes to
  20937. different virtual key codes:
  20938.  
  20939.   Key           Raw key code    Virtual key code
  20940.  
  20941.   Control           36                3B
  20942.   Left cursor       3B                7B
  20943.   Right cursor      3C                7C
  20944.   Down cursor       3D                7D
  20945.   Up cursor         3E                7E
  20946.  
  20947. The standard 'KMAP' resource leaves all other raw key codes and virtual key codes the
  20948. same.
  20949.  
  20950. With the Apple Extended Keyboard, the virtual key codes for three more keys may be
  20951. easily reassigned, as described above under “Reassigning Right Key Codes”.
  20952.  
  20953. The following predefined constants are available to help you access the character
  20954. code and key code:
  20955.  
  20956. CONST  charCodeMask = $000000FF;    {character code}
  20957.        keyCodeMask  = $0000FF00;    {key code}
  20958.  
  20959. •••Refer to Figure 3.•••
  20960.  
  20961. Figure 3–Key Codes
  20962.  
  20963. •••Refer to Figure 4.•••
  20964.  
  20965. Figure 4–Macintosh Plus Keyboard
  20966.  
  20967. •••Refer to Figure 5.•••
  20968.  
  20969. Figure 5–Macintosh II Keyboard
  20970.  
  20971. •••Refer to Figure 6.•••
  20972.  
  20973. Figure 6–Apple Extended Keyboard
  20974.  
  20975. Note:  You can use the Toolbox Utility function BitAnd with these constants;
  20976.        for instance, to access the character code, use
  20977.  
  20978.          charCode := BitAnd(my Event.message,charCodeMask)
  20979. _______________________________________________________________________________
  20980.  
  20981. THE TOOLBOX EVENT MANAGER                                           
  20982. _______________________________________________________________________________
  20983.  
  20984. For activate and update events, the event message is a pointer to the window affected.
  20985. (If the event is an activate event, additional important information about the event
  20986. can be found in the modifiers field of the event record, as described below.)
  20987.  
  20988. For disk-inserted events, the low-order word of the event message contains the drive
  20989. number of the disk drive into which the disk was inserted:  1 for the Macintosh’s
  20990. built-in drive, and 2 for the external drive, if any. Numbers greater than 2 denote
  20991. additional disk drives connected to the Macintosh. By the time your application
  20992. receives a disk-inserted event, the system will already have attempted to mount the
  20993. volume on the disk by calling the File Manager function MountVol; the high-order word
  20994. of the event message will contain the result code returned by MountVol.
  20995.  
  20996. For mouse-down, mouse-up, and null events, the event message is undefined and should
  20997. be ignored. The event message for a network event contains a handle to a parameter
  20998. block, as described in the AppleTalk Manager chapter. For device driver events, the
  20999. contents of the event message depend on the situation under which the event was
  21000. generated; the chapters describing those situations will give the details. Finally,
  21001. you can use the event message however you wish for application-defined event types.
  21002.  
  21003. _______________________________________________________________________________
  21004.  
  21005. »Modifier Flags
  21006.  
  21007. As mentioned above, the modifiers field of an event record contains further information
  21008. about activate events and the state of the modifier keys and mouse button at the time
  21009. the event was posted (see Figure 7). You might look at this field to find out, for
  21010. instance, whether the Command key was down when a mouse-down event was posted (which
  21011. in many applications affects the way objects are selected) or when a key-down event
  21012. was posted (which could mean the user is choosing a menu item by typing its keyboard
  21013. equivalent).
  21014.  
  21015. •••Refer to Figure 7.•••
  21016.  
  21017. Figure 7–Modifier Flags
  21018.  
  21019. The following predefined constants are useful as masks for reading the flags in the
  21020. modifiers field:
  21021.  
  21022. CONST  activeFlag = 1;     {set if window being activated}
  21023.        btnState   = 128;   {set if mouse button up}
  21024.        cmdKey     = 256;   {set if Command key down}
  21025.        shiftKey   = 512;   {set if Shift key down}
  21026.        alphaLock  = 1024;  {set if Caps Lock key down}
  21027.        optionKey  = 2048;  {set if Option key down}
  21028.        ControlKey = 4096;  {set if Control key down}
  21029.  
  21030. The activeFlag bit gives further information about activate events; it’s set if the
  21031. window pointed to by the event message is being activated, or 0 if the window is
  21032. being deactivated. The remaining bits indicate the state of the mouse button and
  21033. modifier keys. Notice that the btnState bit is set if the mouse button is up, whereas
  21034. the bits for the four modifier keys are set if their corresponding keys are down.
  21035.  
  21036. æKY GetNextEvent
  21037. æFc Events.h
  21038. æT Function
  21039. æTN A970
  21040. æD pascal Boolean GetNextEvent(short eventMask,EventRecord *theEvent)
  21041.     = 0xA970; 
  21042. æDT Boolean myVariable = GetNextEvent((short) eventMask,(EventRecord *) theEvent);
  21043. æMM
  21044. æRT 3, 5, 85, 194, 205 
  21045. æRI I-257, N3-1, N5-1, N85, P-30, 32, 34, 39, 40, 97, 108, 173
  21046. æC 
  21047. GetNextEvent returns the next available event of a specified type or types and, if
  21048. the event is in the event queue, removes it from the queue. The event is returned in
  21049. the parameter theEvent. The eventMask parameter specifies which event types are of
  21050. interest. GetNextEvent returns the next available event of any type designated by the
  21051. mask, subject to the priority rules discussed above under “Priority of Events”. If no
  21052. event of any of the designated types is available, GetNextEvent returns a null event.
  21053.  
  21054. Note:  Events in the queue that aren’t designated in the mask are kept in
  21055.        the queue; if you want to remove them, you can do so by calling the
  21056.        Operating System Event Manager procedure FlushEvents.
  21057.  
  21058. Before reporting an event to your application, GetNextEvent first calls the Desk
  21059. Manager function SystemEvent to see whether the system wants to intercept and respond
  21060. to the event. If so, or if the event being reported is a null event, GetNextEvent
  21061. returns a function result of FALSE; a function result of TRUE means that your application
  21062. should handle the event itself. The Desk Manager intercepts the following events:
  21063.  
  21064.   •  activate and update events directed to a desk accessory
  21065.   •  mouse-up and keyboard events, if the currently active window belongs to
  21066.      a desk accessory
  21067.  
  21068. Note:  In each case, the event is intercepted by the Desk Manager only if
  21069.        the desk accessory can handle that type of event; however, as a rule
  21070.        all desk accessories should be set up to handle activate, update, and
  21071.        keyboard events and should not handle mouse-up events.
  21072.  
  21073. The Desk Manager also intercepts disk-inserted events:  It attempts to mount the
  21074. volume on the disk by calling the File Manager function MountVol. GetNextEvent will
  21075. always return TRUE in this case, though, so that your application can take any further
  21076. appropriate action after examining the result code returned by MountVol in the event
  21077. message. (See the Desk Manager and File Manager chapters.) GetNextEvent returns TRUE
  21078. for all other non-null events
  21079. (including all mouse-down events, regardless of which window is active), leaving them
  21080. for your application to handle.
  21081.  
  21082. GetNextEvent also makes the following processing happen, invisible to your program:
  21083.  
  21084.   •  If the “alarm” is set and the current time is the alarm time, the alarm
  21085.      goes off (a beep followed by blinking the apple symbol in the menu bar).
  21086.      The user can set the alarm with the Alarm Clock desk accessory.
  21087.   •  If the user holds down the Command and Shift keys while pressing a
  21088.      numeric key that has a special effect, that effect occurs. The standard
  21089.      such keys are 1 and 2 for ejecting the disk in the internal or external
  21090.      drive, and 3 and 4 for writing a snapshot of the screen to a MacPaint
  21091.      document or to the printer.
  21092.  
  21093. Note:  Advanced programmers can implement their own code to be executed in
  21094.        response to Command-Shift-number combinations (except for Command-
  21095.        Shift-1 and 2, which can’t be changed). The code corresponding to a
  21096.        particular number must be a routine having no parameters, stored in
  21097.        a resource whose type is 'FKEY' and whose ID is the number. The
  21098.        system resource file contains code for the numbers 3 and 4.
  21099.  
  21100. Assembly-language note:  You can disable GetNextEvent’s processing of Command-
  21101.                          Shift-number combinations by setting the global
  21102.                          variable ScrDmpEnb (a byte) to 0.
  21103.  
  21104. æKY WaitNextEvent
  21105. æFc Events.h
  21106. æT Function
  21107. æTN A860
  21108. æD pascal Boolean WaitNextEvent(short mask,EventRecord *event,unsigned long sleep,
  21109.     RgnHandle mouseRgn)
  21110.     = 0xA860; 
  21111. æDT Boolean myVariable = WaitNextEvent((short) mask,(EventRecord *) event,(unsigned long) sleep,()
  21112.     RgnHandle mouseRgn);
  21113. æRT 158, 177, 180, 194, 205
  21114. æRI N158-1
  21115. æC 
  21116.  
  21117. æKY EventAvail
  21118. æFc Events.h
  21119. æT Function
  21120. æTN A971
  21121. æD pascal Boolean EventAvail(short eventMask,EventRecord *theEvent)
  21122.     = 0xA971; 
  21123. æDT Boolean myVariable = EventAvail((short) eventMask,(EventRecord *) theEvent);
  21124. æMM
  21125. æRT 194
  21126. æRI I-259
  21127. æC 
  21128. EventAvail works exactly the same as GetNextEvent except that if the event is in the
  21129. event queue, it’s left there.
  21130.  
  21131. Note:  An event returned by EventAvail will not be accessible later if in
  21132.        the meantime the queue becomes full and the event is discarded from
  21133.        it; since the events discarded are always the oldest ones in the queue,
  21134.        however, this will happen only in an unusually busy environment.
  21135.  
  21136. æKY GetMouse
  21137. æFc Events.h
  21138. æT Function
  21139. æTN A972
  21140. æD pascal void GetMouse(Point *mouseLoc)
  21141.     = 0xA972; 
  21142. æDT GetMouse((Point *) mouseLoc);
  21143. æMM
  21144. æRI I-259
  21145. æC  
  21146. GetMouse returns the current mouse location in the mouseLoc parameter. The location
  21147. is given in the local coordinate system of the current grafPort (which might be, for
  21148. example, the currently active window). Notice that this differs from the mouse location
  21149. stored in the where field of an event record; that location is always in global
  21150. coordinates.
  21151.  
  21152. æKY Button
  21153. æFc Events.h
  21154. æT Function
  21155. æTN A974
  21156. æD pascal Boolean Button(void)
  21157.     = 0xA974; 
  21158. æDT Boolean myVariable = Button()(void);
  21159. æMM
  21160. æRI I-259
  21161. æC 
  21162. The Button function returns TRUE if the mouse button is currently down, and FALSE if
  21163. it isn’t.
  21164.  
  21165. æKY StillDown
  21166. æFc Events.h
  21167. æT Function
  21168. æTN A973
  21169. æD pascal Boolean StillDown(void)
  21170.     = 0xA973; 
  21171. æDT Boolean myVariable = StillDown()(void);
  21172. æMM
  21173. æRT 194
  21174. æRI I-259
  21175. æC 
  21176. Usually called after a mouse-down event, StillDown tests whether the mouse button is
  21177. still down. It returns TRUE if the button is currently down and there are no more
  21178. mouse events pending in the event queue. This is a true test of whether the button is
  21179. still down from the original press—unlike Button (above), which returns TRUE whenever
  21180. the button is currently down, even if it has been released and pressed again since
  21181. the original mouse-down event.
  21182.  
  21183. æKY WaitMouseUp
  21184. æFc Events.h
  21185. æT Function
  21186. æTN A977
  21187. æD pascal Boolean WaitMouseUp(void)
  21188.     = 0xA977; 
  21189. æDT Boolean myVariable = WaitMouseUp()(void);
  21190. æMM
  21191. æRT 194
  21192. æRI I-259
  21193. æC 
  21194. WaitMouseUp works exactly the same as StillDown (above), except that if the button is
  21195. not still down from the original press, WaitMouseUp removes the preceding mouse-up
  21196. event before returning FALSE. If, for instance, your application attaches some special
  21197. significance both to mouse double-clicks and to mouse-up events, this function would
  21198. allow your application to recognize a double-click without being confused by the
  21199. intervening mouse-up.
  21200.  
  21201. æKY GetKeys
  21202. æFc Events.h
  21203. æT Function
  21204. æTN A976
  21205. æD pascal void GetKeys(KeyMap theKeys)
  21206.     = 0xA976; 
  21207. æDT GetKeys((KeyMap) theKeys);
  21208. æMM
  21209. æRI I-259
  21210. æC 
  21211. GetKeys reads the current state of the keyboard (and keypad, if any) and returns it
  21212. in the form of a keyMap:
  21213.  
  21214. TYPE KeyMap = PACKED ARRAY[0..127] OF BOOLEAN;
  21215.  
  21216. Each key on the keyboard or keypad corresponds to an element in the keyMap. The index
  21217. into the keyMap for a particular key is the same as the key code for that key. (The
  21218. key codes are shown in Figure 3 above.) The keyMap element is TRUE if the corresponding
  21219. key is down and FALSE if it isn’t. The maximum number of keys that can be down simultaneously
  21220. is two character keys plus any combination of the four modifier keys.
  21221.  
  21222. æKY TickCount
  21223. æFc Events.h
  21224. æT Function
  21225. æTN A975
  21226. æD pascal unsigned long TickCount(void)
  21227.     = 0xA975; 
  21228. æDT unsigned long myVariable = TickCount()(void);
  21229. æMM
  21230. æRI I-260
  21231. æC 
  21232. TickCount returns the current number of ticks (sixtieths of a second) since the
  21233. system last started up.
  21234.  
  21235. Warning:  Don’t rely on the tick count being exact; it will usually be
  21236.           accurate to within one tick, but may be off by more than that. The
  21237.           tick count is incremented during the vertical retrace interrupt,
  21238.           but it’s possible for this interrupt to be disabled. Furthermore,
  21239.           don’t rely on the tick count being incremented to a certain value,
  21240.           such as testing whether it has become equal to its old value plus 1;
  21241.           check instead for “greater than or equal to” (since an interrupt
  21242.           task may keep control for more than one tick).
  21243.  
  21244. Assembly-language note:  The value returned by this function is also contained
  21245.                          in the global variable Ticks.
  21246.  
  21247. æKY GetDblTime
  21248. æFc Events.h
  21249. æT Function
  21250. æD pascal unsigned long GetDblTime(void)
  21251.     = {0x2EB8,0x02F0}; 
  21252. æDT unsigned long myVariable = GetDblTime()(void);
  21253. æRI I-260
  21254. æC 
  21255. [Not in ROM]
  21256.  
  21257. GetDblTime returns the suggested maximum difference (in ticks) that should exist
  21258. between the times of a mouse-up event and a mouse-down event for those two mouse
  21259. clicks to be considered a double-click. The user can adjust this value by means of
  21260. the Control Panel desk accessory.
  21261.  
  21262. Assembly-language note:  This value is available to assembly-language
  21263.                          programmers in the global variable DoubleTime.
  21264.  
  21265. æKY GetCaretTime
  21266. æFc Events.h
  21267. æT Function
  21268. æD pascal unsigned long GetCaretTime(void)
  21269.     = {0x2EB8,0x02F4}; 
  21270. æDT unsigned long myVariable = GetCaretTime()(void);
  21271. æRI I-260
  21272. æC 
  21273. [Not in ROM]
  21274.  
  21275. GetCaretTime returns the time (in ticks) between blinks of the “caret” (usually a
  21276. vertical bar) marking the insertion point in editable text. If you aren’t using
  21277. TextEdit, you’ll need to cause the caret to blink yourself; on every pass through
  21278. your program’s main event loop, you should check this value against the elapsed time
  21279. since the last blink of the caret. The user can adjust this value by means of the
  21280. Control Panel desk accessory.
  21281.  
  21282. Assembly-language note:  This value is available to assembly-language
  21283.                          programmers in the global variable CaretTime.
  21284.  
  21285.  
  21286. æKY FCntl.h
  21287. æC 
  21288. close    faccess    open    unlink
  21289. creat    fcntl      read    write
  21290. dup      lseek      
  21291.  
  21292. F_DELETE       F_OPEN         O_APPEND    O_RDWR
  21293. F_DUPFD        F_RENAME       O_CREAT     O_RSRC
  21294. F_GFONTINFO    F_SFONTINFO    O_EXCL      O_TRUNC
  21295. F_GPRINTREC    F_SPRINTREC    O_RDONLY    O_WRONLY
  21296. F_GTABINFO     F_STABINFO     
  21297.  
  21298. Low-level file I/O (non-ANSI extensions)—FCntl.h
  21299. non-ANSI extensions:low-level file I/O
  21300. MPW 3.0 C contains several file-control functions in addition to those required  
  21301. by the ANSI draft C standard. These functions, declared in the header file  
  21302. FCntl.h, preserve compatibility with MPW 2.0 C. 
  21303. Some of these functions duplicate, at a lower level, functions in the header  
  21304. file StdIO.h. (For example, open is a low-level equivalent of fopen.) Using  
  21305. the StdIO.h functions whenever possible will improve portability and robustness.
  21306.  
  21307. æKY close
  21308. æFc FCntl.h
  21309. æC                           Synopsis
  21310.  
  21311. #include <FCntl.h>
  21312. int close(int fildes);
  21313.  
  21314.                            Description
  21315.  
  21316. The close; function closes the file descriptor indicated by fildes. 
  21317. Parameter fildes is a file descriptor obtained from an open, creat, 
  21318. dup, or fcntl call. 
  21319. The function close fails if fildes is not a valid open file descriptor [EBADF].
  21320.  
  21321.                           Diagnostics
  21322.  
  21323. Upon successful completion, a value of 0 is returned. Otherwise, a value 
  21324. of –1 is returned and errno is set to indicate the error.
  21325.  
  21326. See also
  21327. creat, dup, fclose, fcntl, ferror, open, stdio
  21328.  
  21329. æKY creat
  21330. æFc FCntl.h
  21331. æC                           Synopsis
  21332.  
  21333. #include <FCntl.h>
  21334. int creat(const char *filename);
  21335.  
  21336.                            Description
  21337.  
  21338. The creat; function creates a new file or prepares to rewrite an existing  
  21339. file, filename. If the file exists, the length of its data fork is set to 0.
  21340. The function creat(filename) is equivalent to open(filename,  
  21341. O_WRONLY|O_TRUNC|O_CREAT)
  21342.  
  21343. Upon successful completion, a nonnegative integer (the file descriptor)  
  21344. is returned and the file is open for writing. The file pointer is set to  
  21345. the beginning of the file. A maximum of about 30 files may be open at a  
  21346. given time: the actual maximum depends upon the current system environment.
  21347.  
  21348.                           Return value
  21349.  
  21350. Upon successful completion, a nonnegative integer (the file descriptor)  
  21351. is returned. Otherwise, a value of –1 is returned and errno is set to  
  21352. indicate the error.
  21353.  
  21354.                            Note
  21355.  
  21356. Other implementations of creat specify a second parameter, mode. This version 
  21357. ignores any second parameter.
  21358.  
  21359. See also
  21360. close, open, read, write
  21361.  
  21362. æKY dup
  21363. æFc FCntl.h
  21364. æC                           Synopsis
  21365.  
  21366. #include <Fcntl.h>
  21367. int dup(int fildes);
  21368.  
  21369.                            Description
  21370.  
  21371. The dup; function returns a new file descriptor with these features:
  21372.  It refers to the same open file as the original.
  21373.  It uses the same file pointer as the original.
  21374.  It has the same access mode (that is, read, write, or read/write) as the 
  21375.  original.
  21376. The fildes parameter is a file descriptor obtained from an open, creat, 
  21377. dup, or fcntl call. The new file descriptor returned by dup is the lowest 
  21378. one available.
  21379. The function call dup(fildes) is equivalent to fcntl(fildes, F_DUPFD, 0).
  21380. The dup function fails if parameter fildes is not a valid open file descriptor 
  21381. [EBADF].
  21382.  
  21383.                           Return value
  21384.  
  21385. Upon successful completion, a nonnegative integer (the file descriptor) 
  21386. is returned. Otherwise, a value of –1 is returned and errno is set to 
  21387. indicate the error.
  21388.  
  21389. See also
  21390. close, fcntl, ferror, open
  21391.  
  21392. æKY F_DELETE
  21393. æFc FCntl.h
  21394. æD #define F_DELETE (('d'<<8)|01)
  21395.  
  21396.  
  21397. æKY F_DUPFD
  21398. æFc FCntl.h
  21399. æD #define F_DUPFD  0 /*Duplicate fildes*/
  21400.  
  21401.  
  21402. æKY F_GFONTINFO
  21403. æFc FCntl.h
  21404. æD #define F_GFONTINFO  (('e'<<8)|02)
  21405.  
  21406.  
  21407. æKY F_GPRINTREC
  21408. æFc FCntl.h
  21409. æD #define F_GPRINTREC  (('e'<<8)|04)
  21410.  
  21411.  
  21412. æKY F_GTABINFO
  21413. æFc FCntl.h
  21414. æD #define F_GTABINFO   (('e'<<8)|00) /*'e' => "editor" ops*/
  21415.  
  21416.  
  21417. æKY F_OPEN
  21418. æFc FCntl.h
  21419. æD #define F_OPEN   (('d'<<8)|00) /*d' => "directory" ops*/
  21420.  
  21421.  
  21422. æKY F_RENAME
  21423. æFc FCntl.h
  21424. æD #define F_RENAME (('d'<<8)|02)
  21425.  
  21426.  
  21427. æKY F_SFONTINFO
  21428. æFc FCntl.h
  21429. æD #define F_SFONTINFO  (('e'<<8)|03)
  21430.  
  21431.  
  21432. æKY F_SPRINTREC
  21433. æFc FCntl.h
  21434. æD #define F_SPRINTREC  (('e'<<8)|05)
  21435.  
  21436.  
  21437. æKY F_STABINFO
  21438. æFc FCntl.h
  21439. æD #define F_STABINFO   (('e'<<8)|01)
  21440.  
  21441.  
  21442. æKY faccess
  21443. æFc FCntl.h
  21444. æC                           Synopsis
  21445.  
  21446. #include <FCntl.h>
  21447. int faccess(const char *filename, unsigned int cmd, long *arg);
  21448.  
  21449.                            Description
  21450.  
  21451. The faccess; function provides access to control and status information for 
  21452. named files. (Compare function ioctl, which provides different control and 
  21453. status information for open files.)
  21454. The cmd parameter must be set to one of the constants in the following list 
  21455. to indicate what operation is to be performed on the file. As Noted in the 
  21456. list, some calls to faccess also require the arg parameter, usually as a 
  21457. long or as a pointer to a long.
  21458. The following commands are available to all programs:
  21459. Value of cmd   Description
  21460.  
  21461. F_DELETE Deletes the named file, or returns an error if the file is open. 
  21462.          Parameter arg is ignored.
  21463. F_RENAME Renames the named file. Parameter arg is a pointer to a string 
  21464.          containing the new name.
  21465.  
  21466. The following commands can be used only by MPW tools:
  21467. Value of cmd Description
  21468.  
  21469. F_GTABINFO   Gets the tab offset for the MPW text file filename. The tab 
  21470.              offset is stored in the long integer pointed to by arg.
  21471.              The tab offset is expressed as an integer number of spaces. 
  21472.              The width of the space character in the current font determines 
  21473.              the actual distance of the tab offset.
  21474. F_STABINFO   Sets the tab offset for the MPW text file filename. The tab 
  21475.              offset is specified as a long value in arg.
  21476. F_GFONTINFO  Gets the font number and font size for an MPW text file 
  21477.              filename. The font number is stored in the high-order half 
  21478.              of the long pointed to by arg; the font size is stored in the 
  21479.              low order half of the same long.
  21480. F_SFONTINFO  Sets the font number and font size for the MPW text file, 
  21481.              filename. The font number is specified in the high-order half 
  21482.              of arg; the font size is specified in the low-order half of arg.
  21483. F_GPRINTREC  Gets a print record TPrint for an MPW text file, filename; arg 
  21484.              is a handle to the print record.
  21485. F_SPRINTREC  Sets a print record for the MPW text file filename; arg is a 
  21486.              handle to the print record.
  21487. F_OPE        Reserved for operating system use.
  21488. F_GSELINFO   Gets the selection information for the MPW text file filename.
  21489. F_SSELINFO   Sets the selection information for the MPW text file filename.
  21490. F_GWININFO   Gets the current window position.
  21491. F_SWININFO   Sets the current window position.
  21492.  
  21493. The commands F_GTABINFO and F_GFONTINFO pass arg as a pointer to a long; 
  21494. F_STABINFO and F_SFONTINFO pass arg as a long value; and F_GPRINTREC and 
  21495. F_SPRINTREC pass arg as a handle to a print record.
  21496.  
  21497.                            Return values
  21498.  
  21499. Upon successful completion, faccess returns a nonnegative value, usually 0. 
  21500. If the device for the named file cannot perform the requested command, 
  21501. faccess returns –1 and errno is set to indicate the error.
  21502. If the requested resource for F_GTABINFO, F_GFONTINFO, or F_GPRINTREC 
  21503. does not exist for the named file, default values are stored and the 
  21504. function returns a value greater than 0.
  21505.  
  21506.                            Note
  21507.  
  21508. Before faccess is called with F_GPRINTREC or F_SPRINTREC, the 
  21509. Printing Manager must be initialized and the print record handle THPrint 
  21510. must be allocated. The font size must be 9, 10, 12, 14, 18, or 24; the 
  21511. font number must be 0 or a positive integer. The following sequence must 
  21512. be used with these print command values:
  21513. res = CurResFile();
  21514. PRClose();
  21515. UseResFile(res);
  21516. PROpen();
  21517.  /* do whatever, including call faccess print commands */
  21518. PRClose();
  21519. UseResFile(res);
  21520.  
  21521. See also
  21522. ioctl, unlink
  21523.  
  21524. æKY fcntl
  21525. æFc FCntl.h
  21526. æC                           Synopsis
  21527.  
  21528. #include <FCntl.h>
  21529. int fcntl(int fildes, unsigned int cmd, int arg);
  21530.  
  21531.                            Description
  21532.  
  21533. The fcntl; function duplicates a file descriptor. A file 
  21534. remains open until all of its file descriptors are closed.
  21535. The fildes parameter is an open file descriptor obtained from 
  21536. an open, creat, dup, or fcntl call. The cmd parameter takes the 
  21537. value F_DUPFD, which tells fcntl to return the lowest-numbered 
  21538. available file descriptor greater than or equal to arg. Normally 
  21539. arg is greater than or equal to 3, to avoid obtaining the standard 
  21540. file descriptors 0, 1, and 2. The function fcntl returns a new 
  21541. file descriptor that points to the same open file as fildes. The 
  21542. new file descriptor has the same access mode (read, write, or 
  21543. read/write) and file pointer as fildes. Any I/O operation 
  21544. changes the file pointer for all file descriptors that share it.
  21545.  
  21546. The fcntl function fails if one or more of the following error 
  21547. conditions are true:
  21548.  Parameter fildes is not a valid open file descriptor [EBADF].
  21549.  Parameter arg is negative or greater than the highest 
  21550.  allowable file descriptor [EINVAL].
  21551.  
  21552.                            Return values
  21553.  
  21554. Upon successful completion, the value returned is a new file 
  21555. descriptor. Otherwise, a value of –1 is returned and errno is 
  21556. set to indicate the error.
  21557.  
  21558.                            Note
  21559.  
  21560. MPW 3.0 C does not support the F_GETFD, F_SETFD, F_GETFL, and 
  21561. F_SETFL commands of fcntl.
  21562.  
  21563. See also
  21564. close, dup, ferror, ioctl, open
  21565.  
  21566. æKY lseek
  21567. æFc FCntl.h
  21568. æC                           Synopsis
  21569.  
  21570. #include <FCntl.h>
  21571. #define SEEK_SET 0
  21572. #define SEEK_CUR 1
  21573. #define SEEK_END 2
  21574. long lseek(int fildes, long int offset, int whence);
  21575.  
  21576.                            Description
  21577.  
  21578. A file descriptor, fildes, is returned from a call to creat, dup, fcntl, 
  21579. or open. The lseek; function sets the file pointer associated with fildes, 
  21580. thus determining the position of the next read or write operation. 
  21581. The value of whence determines how the offset parameter is used, according 
  21582. to these rules:
  21583.  If whence is SEEK_SET, the new position is offset bytes from the beginning 
  21584.  of the file.
  21585.  If whence is SEEK_CUR, the new position is the current location plus offset.
  21586.  If whence is SEEK_END, the new position is the size of the file plus offset.
  21587.  If whence is SEEK_SET or SEEK_CUR, the value of offset may be negative.
  21588. Upon successful completion, the file-pointer value as measured in bytes from 
  21589. the beginning of the file is returned.
  21590. The file pointer remains unchanged and lseek fails if one or more of the 
  21591. following error conditions are true:
  21592.  File descriptor fildes is not open [EBADF].
  21593.  Parameter whence is not equal to SEEK_SET, SEEK_CUR, or SEEK_END [EINVAL].
  21594.  The resulting file pointer would point past the end-of-file [ESPIPE].
  21595.  The resulting file pointer would point before the beginning of the file [EINVAL].
  21596. Some devices are incapable of seeking. The value of the file pointer associated 
  21597. with such a device is undefined.
  21598.  
  21599.                            Return values
  21600.  
  21601. Upon successful completion, a nonnegative long integer indicating the 
  21602. file-pointer value is returned. Otherwise, a value of –1 is returned 
  21603. and errno is set to indicate the error.
  21604.  
  21605.                            Note
  21606.  
  21607. In previous versions of the Standard C Library, tell;(fildes) was a function 
  21608. that returned the current file position. It is equivalent to the call 
  21609. lseek(fildes, 0L, 1).
  21610.  
  21611.                            Warning
  21612.  
  21613. The lseek function has no effect on a file opened with the O_APPEND flag 
  21614. because the next write to the file always repositions the file pointer to 
  21615. the end before writing.
  21616.  
  21617. See also
  21618. ferror, fseek, open, stdio, write
  21619.  
  21620. æKY O_APPEND
  21621. æFc FCntl.h
  21622. æD #define O_APPEND (1<<3) /*append (writes guaranteed at the end)*/
  21623.  
  21624.  
  21625. æKY O_CREAT
  21626. æFc FCntl.h
  21627. æD #define O_CREAT  (1<<8) /*Open with file create*/
  21628.  
  21629.  
  21630. æKY O_EXCL
  21631. æFc FCntl.h
  21632. æD #define O_EXCL   (1<<10) /*Exclusive open*/
  21633.  
  21634.  
  21635. æKY O_RDONLY
  21636. æFc FCntl.h
  21637. æD #define O_RDONLY 0 /*Bits 0 and 1 are used internally*/
  21638.  
  21639.  
  21640. æKY O_RDWR
  21641. æFc FCntl.h
  21642. æD #define O_RDWR   2
  21643.  
  21644.  
  21645. æKY O_RSRC
  21646. æFc FCntl.h
  21647. æD #define O_RSRC   (1<<4) /*Open the resource fork*/
  21648.  
  21649.  
  21650. æKY O_TRUNC
  21651. æFc FCntl.h
  21652. æD #define O_TRUNC  (1<<9) /*Open with truncation*/
  21653.  
  21654.  
  21655. æKY O_WRONLY
  21656. æFc FCntl.h
  21657. æD #define O_WRONLY 1 /*Values 0..2 are historical*/
  21658.  
  21659.  
  21660. æKY open
  21661. æFc FCntl.h
  21662. æC                           Synopsis
  21663.  
  21664. #include <FCntl.h>
  21665. int open(const char *filename, int oflag);
  21666.  
  21667.                            Description
  21668.  
  21669. The open; function opens a file descriptor for the named file and sets the  
  21670. file-status flags according to the value of oflag. The parameter filename 
  21671. is a disk file, window, selection, or pseudofile. (See “Pseudo-Filenames”  
  21672. in Chapter 5 of the Macintosh Programmer’s Workshop 3.0 Reference for more  
  21673. information.) The value of oflag is constructed by performing an OR operation 
  21674. on the flag settings, for example:
  21675. fildes = open("MyFile", O_WRONLY|O_CREAT|O_TRUNC);
  21676. To construct oflag, first select one of the following access modes:
  21677.  O_RDONLY    Open for reading only.
  21678.  WR_ONLY     Open for writing only.
  21679.  O_RDWR      Open for reading and writing.
  21680.  
  21681. Then optionally add one or more of these modifiers:
  21682.  O_APPEND    The file pointer is set to the end of the file before each write.
  21683.  O_CREAT     If the file does not exist, it is created.
  21684.  O_TRUNC     If the file exists, its length is truncated to 0; the mode is  
  21685.              unchanged.
  21686.  O_RSRC      The file’s resource fork is opened. (Normally, the data fork is  
  21687.              opened.)
  21688.  O_BINARY    Open as a binary stream (supported but not used by the system).
  21689.  
  21690. The following setting is valid only if O_CREAT is also specified:
  21691.  O_EXCL      The function open fails if the file exists.
  21692.              Upon successful completion, a nonnegative integer (the file  
  21693.              descriptor) is returned. The file pointer used to mark the  
  21694.              current position within the file is set to the beginning of  
  21695.              the file.
  21696.  
  21697. The named file is opened unless one or more of the following error  
  21698. conditions is true:
  21699.  O_CREAT is not set and the named file does not exist [ENOENT].
  21700.  More than about 30 file descriptors are currently open. The actual limit 
  21701.  varies according to run-time conditions [EMFILE].
  21702.  O_CREAT and O_EXCL are set and the named file exists [EEXIST].
  21703.  
  21704.                           Return value
  21705.  
  21706. Upon successful completion, a nonnegative integer (the file descriptor)  
  21707. is returned. Otherwise, a value of –1 is returned and errno is set to  
  21708. indicate the error.
  21709.  
  21710. See also
  21711. close, creat, dup, fcntl, ferror, fopen, lseek, read, stdio, write
  21712.  
  21713. æKY read
  21714. æFc FCntl.h
  21715. æC                           Synopsis
  21716.  
  21717. #include <Fcntl.h>
  21718. int read(int fildes, char* buf, unsigned long nbyte);
  21719.  
  21720.                            Description
  21721.  
  21722. The read; function transfers up to nbyte bytes from the file associated 
  21723. with fildes into the buffer pointed to by buf. File descriptor fildes is
  21724. obtained from a call to open, creat, a, or a.
  21725. On devices capable of seeking, read starts reading at the current position 
  21726. of the file pointer associated with fildes. Upon return from read, the 
  21727. file pointer is incremented by the number of bytes actually read.
  21728. Nonseeking devices always read from the current position. The value of a 
  21729. file pointer associated with such a file is undefined.
  21730.  
  21731. Upon successful completion, read returns the number of bytes actually read 
  21732. and placed in the buffer. This number may be less than nbyte if the file 
  21733. is associated with a window or if the number of bytes left in the file is 
  21734. less than nbyte bytes. A value of 0 is returned when an end-of-file has 
  21735. been reached, and a value of –1 is returned if a read error occurred.
  21736. The function read fails if fildes is not a valid file descriptor open for
  21737. reading. [EBADF]
  21738. File descriptor 0 is opened by the MPW Shell as standard input.
  21739.  
  21740.                            Return values
  21741.  
  21742. Upon successful completion, a nonnegative integer is returned, indicating 
  21743. the number of bytes actually read. Otherwise, –1 is returned and errno is 
  21744. set to indicate the error.
  21745.  
  21746. See also
  21747. creat, ferror, fread, open, stdio
  21748.  
  21749. æKY unlink
  21750. æFc FCntl.h
  21751. æC                           Synopsis
  21752.  
  21753. #include <FCntl.h>
  21754. int unlink(const char *fileName);
  21755.  
  21756.                            Description
  21757.  
  21758. The unlink; function deletes the named file. The function fails if the 
  21759. named file is open. This function is the UNIX (and MPW 2.0 C) equivalent
  21760.  of the ANSI remove function, and is included for compatibility.
  21761. A call to unlink is equivalent to faccess(fileName, F_DELETE, 0)
  21762.  
  21763.                           Diagnostics
  21764.  
  21765. Upon successful completion, a value of 0 is returned. Otherwise, a value 
  21766. of –1 is returned and errno is set to indicate the error.
  21767.  
  21768. See also
  21769. faccess
  21770.  
  21771. æKY write
  21772. æFc FCntl.h
  21773. æC                           Synopsis
  21774.  
  21775. #include <Fcntl.h>
  21776. int write(int fildes, const char* buf, unsigned long nbyte);
  21777.  
  21778.                            Description
  21779.  
  21780. The write; function attempts to write nbyte bytes from the buffer pointed 
  21781. to by buf to the file associated with the fildes. File descriptor fildes 
  21782. is obtained from an open, creat, dup, or fcntl call. Internal limitations 
  21783. may cause write to write fewer bytes than requested; the number of bytes 
  21784. actually written is indicated by the return value. Several calls to write 
  21785. may therefore be necessary to write out the contents of buf.
  21786. On devices capable of seeking, the actual writing of data proceeds from the 
  21787. position in the file indicated by the file pointer. Upon return from write, 
  21788. the file pointer is incremented by the number of bytes actually written.
  21789. On nonseeking devices, writing starts at the current position. The value of 
  21790. a file pointer associated with such a device is undefined.
  21791. If the O_APPEND file-status flag set in open is on, the file pointer is set 
  21792. to end-of-file before each write.
  21793. The file pointer remains unchanged and write fails if fildes is not a valid 
  21794. file descriptor open for writing [EBADF].
  21795. If you try to write more bytes than there is room for on the device, write 
  21796. writes as many bytes as possible. For example, if nbyte is 512 and there is 
  21797. room for 20 bytes more on the device, write writes 20 bytes and returns a 
  21798. value of 20. The next attempt to write a nonzero number of bytes will return 
  21799. an error [ENOSPC].
  21800. File descriptor 1 is opened by the MPW Shell as standard output; file 
  21801. descriptor 2, as standard error.
  21802.  
  21803.                           Return value
  21804.  
  21805. Upon successful completion, the number of bytes actually written is returned. 
  21806. Otherwise, –1 is returned and errno is set to indicate the error.
  21807.  
  21808. See also
  21809. creat, ferror, fread, lseek, open, stdio
  21810.  
  21811. æKY closeæ
  21812. æDT 
  21813. int myVariabel = close((int) fildes);
  21814.  
  21815. æKY creatæ
  21816. æDT
  21817. int myVariable = creat((const char *)filename);
  21818.  
  21819. æKY dupæ
  21820. æDT 
  21821. int myVariable = dup((int) fildes);
  21822.  
  21823. æKY faccessæ
  21824. æDT 
  21825. int myVariablle =faccess((const char *)filename, (unsigned int) cmd, (long *)arg);
  21826.  
  21827. æKY fcntlæ
  21828. æDT 
  21829. int myVaraible = fcntl((int) fildes, (unsigned int) cmd, (int) arg);
  21830.  
  21831. æKY lseekæ
  21832. æDT 
  21833. long myVariable = lseek((int) fildes, (long int) offset, (int) whence);
  21834.  
  21835. æKY openæ
  21836. æDT 
  21837. int myVariable = open((const char *)filename, (int) oflag);
  21838.  
  21839. æKY readæ
  21840. æDT 
  21841. int myVariable = read((int) fildes, (char*) buf, (unsigned long) nbyte);
  21842.  
  21843. æKY unlinkæ
  21844. æDT 
  21845. int myVariable = unlink((const char *)fileName);
  21846.  
  21847.  
  21848. æKY writeæ
  21849. æDT 
  21850. int myVariable = write((int) fildes, (const char*) buf, (unsigned long) nbyte);
  21851.  
  21852.  
  21853. æKY Files.h
  21854. æKL AddDrive
  21855. Allocate
  21856. AllocContig
  21857. CatMove
  21858. CloseWD
  21859. Create
  21860. create
  21861. DirCreate
  21862. Eject
  21863. eject
  21864. FInitQueue
  21865. flushvol
  21866. FlushVol
  21867. FSClose
  21868. FSDelete
  21869. fsdelete
  21870. fsopen
  21871. FSOpen
  21872. FSpCatMove
  21873. FSpCreate
  21874. FSpCreateResFile
  21875. FSpDelete
  21876. FSpDirCreate
  21877. FSpGetFInfo
  21878. FSpOpenDF
  21879. FSpOpenResFile
  21880. FSpOpenRF
  21881. FSpRename
  21882. FSpRstFLock
  21883. FSpSetFInfo
  21884. FSpSetFLock
  21885. FSRead
  21886. fsrename
  21887. FSWrite
  21888. GetDrvQHdr
  21889. GetEOF
  21890. GetFInfo
  21891. getfinfo
  21892. GetFPos
  21893. GetFSQHdr
  21894. GetVCBQHdr
  21895. getvinfo
  21896. GetVInfo
  21897. GetVol
  21898. getvol
  21899. GetVRefNum
  21900. GetWDInfo
  21901. HCreate
  21902. HDelete
  21903. HGetFInfo
  21904. HGetVol
  21905. HOpen
  21906. HOpenRF
  21907. HRename
  21908. HRstFLock
  21909. HSetFInfo
  21910. HSetFLock
  21911. HSetVol
  21912. MakeFSSpec
  21913. OpenRF
  21914. openrf
  21915. OpenWD
  21916. PBAllocate
  21917. PBAllocContig
  21918. PBCatMove
  21919. PBCatSearch
  21920. PBClose
  21921. PBCloseWD
  21922. PBCreate
  21923. PBCreateFileID
  21924. PBDelete
  21925. PBDeleteFileID
  21926. PBDirCreate
  21927. PBDTAddAPPL
  21928. PBDTAddIcon
  21929. PBDTCloseDown
  21930. PBDTDelete
  21931. PBDTFlush
  21932. PBDTGetAPPL
  21933. PBDTGetComment
  21934. PBDTGetIcon
  21935. PBDTGetIconInfo
  21936. PBDTGetInfo
  21937. PBDTGetPath
  21938. PBDTOpenInform
  21939. PBDTRemoveAPPL
  21940. PBDTRemoveComment
  21941. PBDTReset
  21942. PBDTSetComment
  21943. PBEject
  21944. PBExchangeFiles
  21945. PBFlushFile
  21946. PBFlushVol
  21947. PBGetAltAccess
  21948. PBGetCatInfo
  21949. PBGetEOF
  21950. PBGetFCBInfo
  21951. PBGetFInfo
  21952. PBGetFPos
  21953. PBGetVInfo
  21954. PBGetVol
  21955. PBGetWDInfo
  21956. PBHCopyFile
  21957. PBHCreate
  21958. PBHDelete
  21959. PBHGetDirAccess
  21960. PBHGetFInfo
  21961. PBHGetLogInInfo
  21962. PBHGetVInfo
  21963. PBHGetVol
  21964. PBHGetVolParms
  21965. PBHMapID
  21966. PBHMapName
  21967. PBHMoveRename
  21968. PBHOpen
  21969. PBHOpenDeny
  21970. PBHOpenDF
  21971. PBHOpenRF
  21972. PBHOpenRFDeny
  21973. PBHRename
  21974. PBHRstFLock
  21975. PBHSetDirAccess
  21976. PBHSetFInfo
  21977. PBHSetFLock
  21978. PBHSetVol
  21979. PBLockRange
  21980. PBMakeFSSpec
  21981. PBMountVol
  21982. PBOffLine
  21983. PBOpen
  21984. PBOpenDF
  21985. PBOpenRF
  21986. PBOpenWD
  21987. PBRead
  21988. PBRename
  21989. PBResolveFileID
  21990. PBRstFLock
  21991. PBSetAltAccess
  21992. PBSetCatInfo
  21993. PBSetEOF
  21994. PBSetFInfo
  21995. PBSetFLock
  21996. PBSetFPos
  21997. PBSetFVers
  21998. PBSetVInfo
  21999. PBSetVol
  22000. PBUnlockRange
  22001. PBUnmountVol
  22002. PBWrite
  22003. Rename
  22004. rstflock
  22005. RstFLock
  22006. SetEOF
  22007. SetFInfo
  22008. setfinfo
  22009. setflock
  22010. SetFLock
  22011. SetFPos
  22012. SetVol
  22013. setvol
  22014. unmountvol
  22015. UnmountVol
  22016.  
  22017. AccessParam
  22018. alphaStage
  22019. AltAccessParam
  22020. AltAccessParamPtr
  22021. betaStage
  22022. CatPositionRec
  22023. CInfoPBPtr
  22024. CInfoPBRec
  22025. CInfoType
  22026. CMovePBPtr
  22027. CMovePBRec
  22028. CntrlParam
  22029. CopyParam
  22030. CSParam
  22031. CSParamPtr
  22032. developStage
  22033. DInfo
  22034. DirInfo
  22035. dirInfo
  22036. DrvQEl
  22037. DrvQElPtr
  22038. DTPBPtr
  22039. DTPBRec
  22040. DXInfo
  22041. FCBPBPtr
  22042. FCBPBRec
  22043. fDesktop
  22044. fDisk
  22045. fHasBundle
  22046. FIDParam
  22047. FileParam
  22048. finalStage
  22049. FInfo
  22050. fInvisible
  22051. fOnDesk
  22052. fsAtMark
  22053. fsCurPerm
  22054. fsFromLEOF
  22055. fsFromMark
  22056. fsFromStart
  22057. fsRdPerm
  22058. fsRdWrPerm
  22059. fsRdWrShPerm
  22060. fsRtDirID
  22061. fsRtParID
  22062. fsSBDrBkDat
  22063. fsSBDrCrDat
  22064. fsSBDrFndrInfo
  22065. fsSBDrMdDat
  22066. fsSBDrNmFls
  22067. fsSBDrParID
  22068. fsSBDrUsrWds
  22069. fsSBFlAttrib
  22070. fsSBFlBkDat
  22071. fsSBFlCrDat
  22072. fsSBFlFndrInfo
  22073. fsSBFlLgLen
  22074. fsSBFlMdDat
  22075. fsSBFlParID
  22076. fsSBFlPyLen
  22077. fsSBFlRLgLen
  22078. fsSBFlRPyLen
  22079. fsSBFlXFndrInfo
  22080. fsSBFullName
  22081. fsSBNegate
  22082. fsSBPartialName
  22083. FSSpec
  22084. FSSpecHandle
  22085. FSSpecPtr
  22086. fsWrPerm
  22087. fTrash
  22088. FXInfo
  22089. HFileInfo
  22090. hFileInfo
  22091. HFileParam
  22092. HIOParam
  22093. HParamBlockRec
  22094. HParmBlkPtr
  22095. HVolumeParam
  22096. ioDirFlg
  22097. ioDirMask
  22098. IOParam
  22099. MultiDevParam
  22100. NumVersion
  22101. ObjParam
  22102. ParamBlockHeader
  22103. ParamBlockRec
  22104. ParmBlkPtr
  22105. rdVerify
  22106. SlotDevParam
  22107. VCB
  22108. VersRec
  22109. VersRecHndl
  22110. VersRecPtr
  22111. VolumeParam
  22112. WDParam
  22113. WDPBPtr
  22114. WDPBRec
  22115.  
  22116. æKY fsAtMark
  22117. æFc Files.h
  22118. æT #define
  22119. æD 
  22120. /* Finder Constants */
  22121.  
  22122. #define fsAtMark 0
  22123. æC 
  22124. IOPosMode and ioPosOffset specify the position of the mark for Read, Write, LockRng,
  22125. UnlockRng, and SetFPos calls. IOPosMode contains the positioning mode; bits 0 and 1
  22126. indicate how to position the mark, and you can use the following predefined constants
  22127. to set or test their value:
  22128.  
  22129. #define  fsAtMark     0    /*at current mark*/
  22130. #define  fsFromStart  1    /*set mark relative to beginning of file*/
  22131. #define  fsFromLEOF   2    /*set mark relative to logical end-of-file*/
  22132. #define  fsFromMark   3    /*set mark relative to current mark*/
  22133.  
  22134. If you specify fsAtMark, ioPosOffset is ignored and the operation begins wherever the
  22135. mark is currently positioned. If you choose to set the mark
  22136. (relative to either the beginning of the file, the logical end-of-file, or the current
  22137. mark), ioPosOffset must specify the byte offset from the chosen point
  22138. (either positive or negative) where the operation should begin.
  22139.  
  22140. Note:  Advanced programmers:  Bit 7 of ioPosMode is the newline flag; it’s
  22141.        set if read operations should terminate at a newline character. The
  22142.        ASCII code of the newline character is specified in the high-order
  22143.        byte of ioPosMode. If the newline flag is set, the data will be read
  22144.        one byte at a time until the newline character is encountered,
  22145.        ioReqCount bytes have been read, or the end-of-file is reached. If
  22146.        the newline flag is clear, the data will be read one byte at a time
  22147.        until ioReqCount bytes have been read or the end-of-file is reached.
  22148.  
  22149. æKY fOnDesk
  22150. æFc Files.h
  22151. æT #define
  22152. æD #define fOnDesk 1
  22153. æC 
  22154.  
  22155. æKY fsCurPerm
  22156. æFc Files.h
  22157. æT #define
  22158. æD #define fsCurPerm 0
  22159. æC 
  22160. IOPermssn requests permission to read or write via an access path, and must contain
  22161. one of the following values:
  22162.  
  22163. #define  fsCurPerm      0    /*whatever is currently allowed*/
  22164. #define  fsRdPerm       1    /*request for read permission only*/
  22165. #define  fsWrPerm       2    /*request for write permission*/
  22166. #define  fsRdWrPerm     3    /*request for exclusive read/write permission*/
  22167. #define  fsRdWrShPerm   4    /*request for shared read/write permission*/
  22168.  
  22169. This request is compared with the open permission of the file. If the open permission
  22170. doesn’t allow I/O as requested, a result code indicating the error is returned.
  22171.  
  22172. Warning:  To ensure data integrity be sure to lock the portion of the
  22173.           file you’ll be using if you specify shared write permission.
  22174.  
  22175. æKY fHasBundle
  22176. æFc Files.h
  22177. æT #define
  22178. æD #define fHasBundle 8192
  22179. æC 
  22180.  
  22181. æKY fsRdPerm
  22182. æFc Files.h
  22183. æT #define
  22184. æD #define fsRdPerm 1
  22185. æC 
  22186.  
  22187. æKY fInvisible
  22188. æFc Files.h
  22189. æT #define
  22190. æD #define fInvisible 16384
  22191. æC 
  22192.  
  22193. æKY fTrash
  22194. æFc Files.h
  22195. æT #define
  22196. æD #define fTrash -3
  22197. æC 
  22198.  
  22199. æKY fsWrPerm
  22200. æFc Files.h
  22201. æT #define
  22202. æD #define fsWrPerm 2
  22203. æC 
  22204.  
  22205. æKY fDesktop
  22206. æFc Files.h
  22207. æT #define
  22208. æD #define fDesktop -2
  22209. æC 
  22210.  
  22211. æKY fsRdWrPerm
  22212. æFc Files.h
  22213. æT #define
  22214. æD #define fsRdWrPerm 3
  22215. æC 
  22216.  
  22217. æKY fDisk
  22218. æFc Files.h
  22219. æT #define
  22220. æD #define fDisk 0
  22221. æC 
  22222.  
  22223. æKY fsRdWrShPerm
  22224. æFc Files.h
  22225. æT #define
  22226. æD #define fsRdWrShPerm 4
  22227. æC 
  22228.  
  22229. æKY fsFromStart
  22230. æFc Files.h
  22231. æT #define
  22232. æD #define fsFromStart 1
  22233. æC 
  22234.  
  22235. æKY fsFromLEOF
  22236. æFc Files.h
  22237. æT #define
  22238. æD #define fsFromLEOF 2
  22239. æC 
  22240.  
  22241. æKY fsFromMark
  22242. æFc Files.h
  22243. æT #define
  22244. æD #define fsFromMark 3
  22245. æC 
  22246.  
  22247. æKY rdVerify
  22248. æFc Files.h
  22249. æT #define
  22250. æD #define rdVerify 64
  22251. æC To have the File Manager verify that all data written to a volume exactly matches the
  22252. data in memory, make a Read call right after the Write call. The parameters for a
  22253. read-verify operation are the same as for a standard Read call, except that the
  22254. following constant must be added to the positioning mode:
  22255.  
  22256. #define rdVerify 64    /*read-verify mode*/
  22257.  
  22258. The result code ioErr is returned if any of the data doesn’t match.
  22259.  
  22260. æKY ioDirFlg
  22261. æFc Files.h
  22262. æT #define
  22263. æD #define ioDirFlg 3
  22264. æC 
  22265.  
  22266. æKY ioDirMask
  22267. æFc Files.h
  22268. æT #define
  22269. æD #define ioDirMask 0x10
  22270. æC 
  22271.  
  22272. æKY fsRtParID
  22273. æFc Files.h
  22274. æT #define
  22275. æD #define fsRtParID 1
  22276. æC 
  22277.  
  22278. æKY fsRtDirID
  22279. æFc Files.h
  22280. æT #define
  22281. æD #define fsRtDirID 2
  22282. æC 
  22283.  
  22284. æKY fsSBNegate
  22285. æFc Files.h
  22286. æT #define
  22287. æD #define fsSBNegate 16384
  22288. æC 
  22289.  
  22290. æKY fsSBPartialName
  22291. æFc Files.h
  22292. æT #define
  22293. æD 
  22294. /*  masks for SpecBits values  */
  22295.  
  22296. #define fsSBPartialName 1
  22297. æC 
  22298.  
  22299. æKY fsSBFullName
  22300. æFc Files.h
  22301. æT #define
  22302. æD #define fsSBFullName 2
  22303. æC 
  22304.  
  22305. æKY fsSBFlAttrib
  22306. æFc Files.h
  22307. æT #define
  22308. æD #define fsSBFlAttrib 4
  22309. æC 
  22310.  
  22311. æKY fsSBFlFndrInfo
  22312. æFc Files.h
  22313. æT #define
  22314. æD #define fsSBFlFndrInfo 8
  22315. æC 
  22316.  
  22317. æKY fsSBFlLgLen
  22318. æFc Files.h
  22319. æT #define
  22320. æD #define fsSBFlLgLen 32
  22321. æC 
  22322.  
  22323. æKY fsSBFlPyLen
  22324. æFc Files.h
  22325. æT #define
  22326. æD #define fsSBFlPyLen 64
  22327. æC 
  22328.  
  22329. æKY fsSBFlRLgLen
  22330. æFc Files.h
  22331. æT #define
  22332. æD #define fsSBFlRLgLen 128
  22333. æC 
  22334.  
  22335. æKY fsSBFlRPyLen
  22336. æFc Files.h
  22337. æT #define
  22338. æD #define fsSBFlRPyLen 256
  22339. æC 
  22340.  
  22341. æKY fsSBFlCrDat
  22342. æFc Files.h
  22343. æT #define
  22344. æD #define fsSBFlCrDat 512
  22345. æC 
  22346.  
  22347. æKY fsSBFlMdDat
  22348. æFc Files.h
  22349. æT #define
  22350. æD #define fsSBFlMdDat 1024
  22351. æC 
  22352.  
  22353. æKY fsSBFlBkDat
  22354. æFc Files.h
  22355. æT #define
  22356. æD #define fsSBFlBkDat 2048
  22357. æC 
  22358.  
  22359. æKY fsSBFlXFndrInfo
  22360. æFc Files.h
  22361. æT #define
  22362. æD #define fsSBFlXFndrInfo 4096
  22363. æC 
  22364.  
  22365. æKY fsSBFlParID
  22366. æFc Files.h
  22367. æT #define
  22368. æD #define fsSBFlParID 8192
  22369. æC 
  22370.  
  22371. æKY fsSBDrUsrWds
  22372. æFc Files.h
  22373. æT #define
  22374. æD #define fsSBDrUsrWds 8
  22375. æC 
  22376.  
  22377. æKY fsSBDrNmFls
  22378. æFc Files.h
  22379. æT #define
  22380. æD #define fsSBDrNmFls 16
  22381. æC 
  22382.  
  22383. æKY fsSBDrCrDat
  22384. æFc Files.h
  22385. æT #define
  22386. æD #define fsSBDrCrDat 512
  22387. æC 
  22388.  
  22389. æKY fsSBDrMdDat
  22390. æFc Files.h
  22391. æT #define
  22392. æD #define fsSBDrMdDat 1024
  22393. æC 
  22394.  
  22395. æKY fsSBDrBkDat
  22396. æFc Files.h
  22397. æT #define
  22398. æD #define fsSBDrBkDat 2048
  22399. æC 
  22400.  
  22401. æKY fsSBDrFndrInfo
  22402. æFc Files.h
  22403. æT #define
  22404. æD #define fsSBDrFndrInfo 4096
  22405. æC 
  22406.  
  22407. æKY fsSBDrParID
  22408. æFc Files.h
  22409. æT #define
  22410. æD #define fsSBDrParID 8192
  22411. æC 
  22412.  
  22413. æKY developStage
  22414. æFc Files.h
  22415. æT #define
  22416. æD 
  22417. /* Version Release Stage Codes */
  22418.  
  22419. #define developStage 0x20
  22420. æC 
  22421.  
  22422. æKY alphaStage
  22423. æFc Files.h
  22424. æT #define
  22425. æD #define alphaStage 0x40
  22426. æC 
  22427.  
  22428. æKY betaStage
  22429. æFc Files.h
  22430. æT #define
  22431. æD #define betaStage 0x60
  22432. æC 
  22433.  
  22434. æKY finalStage
  22435. æFc Files.h
  22436. æT #define
  22437. æD #define finalStage 0x80
  22438. æC 
  22439.  
  22440. æKY CInfoType
  22441. hFileInfo
  22442. dirInfo
  22443. æFc Files.h
  22444. æT enum
  22445. æD enum {hFileInfo,dirInfo};
  22446. typedef unsigned char CInfoType;
  22447. æC 
  22448.  
  22449. æKY FInfo
  22450. æFc Files.h
  22451. æT struct
  22452. æD struct FInfo {
  22453.     OSType fdType; /*the type of the file*/
  22454.     OSType fdCreator; /*file's creator*/
  22455.     unsigned short fdFlags; /*flags ex. hasbundle,invisible,locked, etc.*/
  22456.     Point fdLocation; /*file's location in folder*/
  22457.     short fdFldr; /*folder containing file*/
  22458. };
  22459.  
  22460. typedef struct FInfo FInfo;
  22461. æC 
  22462.  
  22463. æKY FXInfo
  22464. æFc Files.h
  22465. æT struct
  22466. æD struct FXInfo {
  22467.     short fdIconID; /*Icon ID*/
  22468.     short fdUnused[4]; /*unused but reserved 8 bytes*/
  22469.     short fdComment; /*Comment ID*/
  22470.     long fdPutAway; /*Home Dir ID*/
  22471. };
  22472.  
  22473. typedef struct FXInfo FXInfo;
  22474. æC 
  22475.  
  22476. On hierarchical volumes, in addition to the FInfo record, the following information
  22477. about files is maintained for the Finder:
  22478.  
  22479. æKY DInfo
  22480. æFc Files.h
  22481. æT struct
  22482. æD struct DInfo {
  22483.     Rect frRect; /*folder rect*/
  22484.     unsigned short frFlags; /*Flags*/
  22485.     Point frLocation; /*folder location*/
  22486.     short frView; /*folder view*/
  22487. };
  22488.  
  22489. typedef struct DInfo DInfo;
  22490. æC 
  22491.  
  22492. On hierarchical volumes, the following information about directories is maintained
  22493. for the Finder:
  22494.  
  22495. DInfo = RECORD
  22496.           frRect:      Rect;       {folder's rectangle}
  22497.           frFlags:     INTEGER;    {flags}
  22498.           frLocation:  Point;      {folder's location}
  22499.           frView:      INTEGER;    {folder's view}
  22500.         END;
  22501.  
  22502. DXInfo = RECORD
  22503.            frScroll:     Point;      {scroll position}
  22504.            frOpenChain:  LONGINT;    {directory ID chain of open folders}
  22505.            frUnused:     INTEGER;    {reserved}
  22506.            frComment:    INTEGER;    {comment ID}
  22507.            frPutAway:    LONGINT;    {directory ID}
  22508.          END;
  22509.  
  22510. When a file (or folder) is moved to the desktop on a hierarchical volume, it’s actually
  22511. moved to the root level of the file directory. (This permits all the desktop icons to
  22512. be enumerated by one simple scan of the root.) The fOnDesk bit of fdFlags is set.
  22513. FDPutAway (or frPutAway for directories) contains the directory ID of the folder that
  22514. originally contained the file (or folder); this allows the file (or folder) to be
  22515. returned there from the desktop.
  22516.  
  22517. æKY DXInfo
  22518. æFc Files.h
  22519. æT struct
  22520. æD struct DXInfo {
  22521.     Point frScroll; /*scroll position*/
  22522.     long frOpenChain; /*DirID chain of open folders*/
  22523.     short frUnused; /*unused but reserved*/
  22524.     short frComment; /*comment*/
  22525.     long frPutAway; /*DirID*/
  22526. };
  22527.  
  22528. typedef struct DXInfo DXInfo;
  22529. æC 
  22530.  
  22531. æKY ParamBlockHeader
  22532. æFc Files.h
  22533. æT struct
  22534. æD #define ParamBlockHeader \
  22535.     QElemPtr qLink; /*queue link in header*/
  22536.     short qType; /*type byte for safety check*/
  22537.     short ioTrap; /*FS: the Trap*/
  22538.     Ptr ioCmdAddr; /*FS: address to dispatch to*/
  22539.     ProcPtr ioCompletion; /*completion routine addr (0 for synch calls)*/
  22540.     OSErr ioResult; /*result code*/
  22541.     StringPtr ioNamePtr; /*ptr to Vol:FileName string*/
  22542.     short ioVRefNum; /*volume refnum (DrvNum for Eject and MountVol)*/
  22543.  
  22544.  
  22545. æC 
  22546.  
  22547. æKY IOParam
  22548. æFc Files.h
  22549. æT struct
  22550. æD struct IOParam {
  22551.     ParamBlockHeader 
  22552.     short ioRefNum; /*refNum for I/O operation*/
  22553.     char ioVersNum; /*version number*/
  22554.     char ioPermssn; /*Open: permissions (byte)*/
  22555.     Ptr ioMisc; /*Rename: new name (GetEOF,SetEOF: logical end of file) (Open: optional ptr to buffer) (SetFileType: new type)*/
  22556.     Ptr ioBuffer; /*data buffer Ptr*/
  22557.     long ioReqCount; /*requested byte count; also = ioNewDirID*/
  22558.     long ioActCount; /*actual byte count completed*/
  22559.     short ioPosMode; /*initial file positioning*/
  22560.     long ioPosOffset; /*file position offset*/
  22561. };
  22562.  
  22563. typedef struct IOParam IOParam;
  22564. æC 
  22565.  
  22566. æKY FileParam
  22567. æFc Files.h
  22568. æT struct
  22569. æD struct FileParam {
  22570.     ParamBlockHeader 
  22571.     short ioFRefNum; /*reference number*/
  22572.     char ioFVersNum; /*version number*/
  22573.     char filler1;
  22574.     short ioFDirIndex; /*GetFInfo directory index*/
  22575.     unsigned char ioFlAttrib; /*GetFInfo: in-use bit=7, lock bit=0*/
  22576.     unsigned char ioFlVersNum; /*file version number*/
  22577.     FInfo ioFlFndrInfo; /*user info*/
  22578.     unsigned long ioFlNum; /*GetFInfo: file number; TF- ioDirID*/
  22579.     unsigned short ioFlStBlk; /*start file block (0 if none)*/
  22580.     long ioFlLgLen; /*logical length (EOF)*/
  22581.     long ioFlPyLen; /*physical length*/
  22582.     unsigned short ioFlRStBlk; /*start block rsrc fork*/
  22583.     long ioFlRLgLen; /*file logical length rsrc fork*/
  22584.     long ioFlRPyLen; /*file physical length rsrc fork*/
  22585.     unsigned long ioFlCrDat; /*file creation date& time (32 bits in secs)*/
  22586.     unsigned long ioFlMdDat; /*last modified date and time*/
  22587. };
  22588.  
  22589. typedef struct FileParam FileParam;
  22590. æC 
  22591.  
  22592. æKY VolumeParam
  22593. æFc Files.h
  22594. æT struct
  22595. æD struct VolumeParam {
  22596.     ParamBlockHeader 
  22597.     long filler2;
  22598.     short ioVolIndex; /*volume index number*/
  22599.     unsigned long ioVCrDate; /*creation date and time*/
  22600.     unsigned long ioVLsBkUp; /*last backup date and time*/
  22601.     unsigned short ioVAtrb; /*volume attrib*/
  22602.     unsigned short ioVNmFls; /*number of files in directory*/
  22603.     unsigned short ioVDirSt; /*start block of file directory*/
  22604.     short ioVBlLn; /*GetVolInfo: length of dir in blocks*/
  22605.     unsigned short ioVNmAlBlks; /*GetVolInfo: num blks (of alloc size)*/
  22606.     long ioVAlBlkSiz; /*GetVolInfo: alloc blk byte size*/
  22607.     long ioVClpSiz; /*GetVolInfo: bytes to allocate at a time*/
  22608.     unsigned short ioAlBlSt; /*starting disk(512-byte) block in block map*/
  22609.     unsigned long ioVNxtFNum; /*GetVolInfo: next free file number*/
  22610.     unsigned short ioVFrBlk; /*GetVolInfo: # free alloc blks for this vol*/
  22611. };
  22612.  
  22613. typedef struct VolumeParam VolumeParam;
  22614. æC 
  22615.  
  22616. æKY CntrlParam
  22617. æFc Files.h
  22618. æT struct
  22619. æD struct CntrlParam {
  22620.     QElem *qLink; /*queue link in header*/
  22621.     short qType; /*type byte for safety check*/
  22622.     short ioTrap; /*FS: the Trap*/
  22623.     Ptr ioCmdAddr; /*FS: address to dispatch to*/
  22624.     ProcPtr ioCompletion; /*completion routine addr (0 for synch calls)*/
  22625.     OSErr ioResult; /*result code*/
  22626.     StringPtr ioNamePtr; /*ptr to Vol:FileName string*/
  22627.     short ioVRefNum; /*volume refnum (DrvNum for Eject and MountVol)*/
  22628.     short ioCRefNum; /*refNum for I/O operation*/
  22629.     short csCode; /*word for control status code*/
  22630.     short csParam[11]; /*operation-defined parameters*/
  22631. };
  22632.  
  22633. typedef struct CntrlParam CntrlParam;
  22634. æC 
  22635.  
  22636. æKY SlotDevParam
  22637. æFc Files.h
  22638. æT struct
  22639. æD struct SlotDevParam {
  22640.     ParamBlockHeader 
  22641.     short ioRefNum;
  22642.     char ioVersNum;
  22643.     char ioPermssn;
  22644.     Ptr ioMix;
  22645.     short ioFlags;
  22646.     char ioSlot;
  22647.     char ioID;
  22648. };
  22649.  
  22650. typedef struct SlotDevParam SlotDevParam;
  22651. æC 
  22652.  
  22653. æKY MultiDevParam
  22654. æFc Files.h
  22655. æT struct
  22656. æD struct MultiDevParam {
  22657.     ParamBlockHeader 
  22658.     short ioRefNum;
  22659.     char ioVersNum;
  22660.     char ioPermssn;
  22661.     Ptr ioMix;
  22662.     short ioFlags;
  22663.     Ptr ioSEBlkPtr;
  22664. };
  22665.  
  22666. typedef struct MultiDevParam MultiDevParam;
  22667. æC 
  22668.  
  22669. æKY ParamBlockRec
  22670. ParmBlkPtr
  22671. æFc Files.h
  22672. æT struct
  22673. æD union ParamBlockRec {
  22674.     IOParam ioParam;
  22675.     FileParam fileParam;
  22676.     VolumeParam volumeParam;
  22677.     CntrlParam cntrlParam;
  22678.     SlotDevParam slotDevParam;
  22679.     MultiDevParam multiDevParam;
  22680. };
  22681.  
  22682. typedef union ParamBlockRec ParamBlockRec;
  22683.  
  22684. typedef ParamBlockRec *ParmBlkPtr;
  22685.  
  22686. æC »FileParam Variant ( ParamBlockRec and HParamBlockRec)
  22687.  
  22688. The fileParam variants of ParamBlockRec and HParamBlockRec are identical, with one
  22689. exception:  The field ioDirID in HParamBlockRec is called ioFlNum in ParamBlockRec.
  22690. The fields of the fileParam variant of HParamBlockRec are as follows:  
  22691.  
  22692. •••Refer to Technical Note #204:•••
  22693.  
  22694.   fileParam:
  22695.    (ioFRefNum:     INTEGER;     {path reference number}
  22696.     ioFVersNum:    SignedByte;  {version number}
  22697.     filler1:       SignedByte;  {not used}
  22698.     ioFDirIndex:   INTEGER;     {index}
  22699.     ioFlAttrib:    SignedByte;  {file attributes}
  22700.     ioFlVersNum:   SignedByte;  {version number}
  22701.     ioFlFndrInfo:  FInfo;       {information used by the Finder}
  22702.     ioDirID:       LONGINT;     {directory ID or file number}
  22703.     ioFlStBlk:     INTEGER;     {first allocation block of data fork}
  22704.     ioFlLgLen:     LONGINT;     {logical end-of-file of data fork}
  22705.     ioFlPyLen:     LONGINT;     {physical end-of-file of data fork}
  22706.     ioFlRStBlk:    INTEGER;     {first allocation block of resource fork}
  22707.     ioFlRLgLen:    LONGINT;     {logical end-of-file of resource fork}
  22708.     ioFlRPyLen:    LONGINT;     {physical end-of-file of resource fork}
  22709.     ioFlCrDat:     LONGINT;     {date and time of creation}
  22710.     ioFlMdDat:     LONGINT);    {date and time of last modification}
  22711.  
  22712. IOFDirIndex can be used with the PBGetFInfo and PBHGetFInfo to index through the
  22713. files in a given directory.
  22714.  
  22715. Warning:  When used with GetFileInfo, ioFDirIndex will index only the files
  22716.           in a directory. To index both files and directories, you can use
  22717.           ioFDirIndex with PBGetCatInfo.
  22718.  
  22719. IOFlAttrib contains the following file attributes:
  22720.  
  22721.   Bit    Meaning
  22722.  
  22723.    0     Set if file is locked
  22724.    2     Set if resource fork is open
  22725.    3     Set if data fork is open
  22726.    4     Set if a directory
  22727.    7     Set if file (either fork) is open
  22728.  
  22729. When passed to a routine, ioDirID contains a directory ID; it can be used to refer to
  22730. a directory or, in conjuction with a partial pathname from that directory, to other
  22731. files and directories. If both a directory ID and a working directory reference
  22732. number are provided, the directory ID is used to identify the directory on the volume
  22733. indicated by the working directory reference number. In other words, a directory ID
  22734. specified by the caller will override the working directory referred to by the working
  22735. directory reference number. If you don’t want this to happen, you can set ioDirID to
  22736. 0. (If no directory is specified through a working directory reference number, the
  22737. root directory ID will be used.)
  22738.  
  22739. When returned from a routine, ioDirID contains the file number of a file; most programmers
  22740. needn’t be concerned with file numbers, but those interested can read the section
  22741. “Data Organization on Volumes”.
  22742.  
  22743. IOFlStBlk and ioFlRStBlk contain 0 if the file’s data or resource fork is empty,
  22744. respectively; they’re used only with flat volumes. The date and time in the ioFlCrDat
  22745. and ioFlMdDat fields are specified in seconds since midnight,
  22746. January 1, 1904.
  22747.  
  22748. »VolumeParam Variant (ParamBlockRec)
  22749.  
  22750. When you call GetVolInfo, you’ll use the volumeParam variant of ParamBlockRec:
  22751.  
  22752.   volumeParam:
  22753.    (filler2:      LONGINT;    {not used}
  22754.     ioVolIndex:   INTEGER;    {index}
  22755.     ioVCrDate:    LONGINT;    {date and time of initialization}
  22756.     ioVLsBkUp:    LONGINT;    {date and time of last modification}
  22757.     ioVAtrb:      INTEGER;    {volume attributes}
  22758.     ioVNmFls:     INTEGER;    {number of files in root directory}
  22759.     ioVDirSt:     INTEGER;    {first block of directory}
  22760.     ioVBlLn:      INTEGER;    {length of directory in blocks}
  22761.     ioVNmAlBlks:  INTEGER;    {number of allocation blocks}
  22762.     ioVAlBlkSiz:  LONGINT;    {size of allocation blocks}
  22763.     ioVClpSiz:    LONGINT;    {number of bytes to allocate}
  22764.     ioAlBlSt:     INTEGER;    {first block in volume block map}
  22765.     ioVNxtFNum:   LONGINT;    {next unused file number}
  22766.     ioVFrBlk:     INTEGER);   {number of unused allocation blocks}
  22767.  
  22768. IOVolIndex can be used to index through all the mounted volumes; using an index of 1
  22769. accesses the first volume mounted, and so on. (For more information on indexing, see
  22770. the section “Indexing” above.)
  22771.  
  22772. IOVLsBkUp contains the date and time the volume information was last modified
  22773. (this is not necessarily when it was flushed). (This field is not modified when
  22774. information is written to a file.)
  22775.  
  22776. Note:  The name ioVLsBkUp is actually a misnomer; this field has always
  22777.        contained the date and time of the last modification to the volume,
  22778.        not the last backup.
  22779.  
  22780. Most programmers needn’t be concerned with the remaining parameters, but interested
  22781. programmers can read the section “Data Organization on Volumes”.
  22782.  
  22783. »VolumeParam Variant (HParamBlockRec)
  22784.  
  22785. When you call HGetVInfo and SetVolInfo, you’ll use the volumeParam variant of HParamBlockRec.
  22786. This is a superset of the volumeParam variant of ParamBlockRec; the names and functions
  22787. of certain fields have been changed, and new fields have been added:
  22788.  
  22789.   volumeParam:
  22790.    (filler2:      LONGINT;    {not used}
  22791.     ioVolIndex:   INTEGER;    {index}
  22792.     ioVCrDate:    LONGINT;    {date and time of initialization}
  22793.     ioVLsMod:     LONGINT;    {date and time of last modification}
  22794.     ioVAtrb:      INTEGER;    {volume attributes}
  22795.     ioVNmFls:     INTEGER;    {number of files in root directory}
  22796.     ioVBitMap:    INTEGER;    {first block of volume bit map}
  22797.     ioAllocPtr:   INTEGER;    {block at which next new file starts}
  22798.     ioVNmAlBlks:  INTEGER;    {number of allocation blocks}
  22799.     ioVAlBlkSiz:  LONGINT;    {size of allocation blocks}
  22800.     ioVClpSiz:    LONGINT;    {number of bytes to allocate}
  22801.     ioAlBlSt:     INTEGER;    {first block in volume block map}
  22802.     ioVNxtCNID:   LONGINT;    {next unused file number}
  22803.     ioVFrBlk:     INTEGER;    {number of unused allocation blocks}
  22804.     ioVSigWord:   INTEGER;    {volume signature}
  22805.     ioVDrvInfo:   INTEGER;    {drive number}
  22806.     ioVDRefNum:   INTEGER;    {driver reference number}
  22807.     ioVFSID:      INTEGER;    {file system handling this volume}
  22808.     ioVBkUp:      LONGINT;    {date and time of last backup}
  22809.     ioVSeqNum:    INTEGER;    {used internally}
  22810.     ioVWrCnt      LONGINT;    {volume write count}
  22811.     ioVFilCnt:    LONGINT;    {number of files on volume}
  22812.     ioVDirCnt:    LONGINT;    {number of directories on volume}
  22813.     ioVFndrInfo:  ARRAY[1..8] OF LONGINT); {information used by the Finder}
  22814.  
  22815. IOVolIndex can be used to index through all the mounted volumes; using an index of 1
  22816. accesses the first volume mounted, and so on. (For more information on indexing, see
  22817. the section “Indexing” above.)
  22818.  
  22819. IOVLsMod contains the date and time the volume information was last modified
  22820. (this is not necessarily when it was flushed). (This field is not modified when
  22821. information is written to a file.)
  22822.  
  22823. Note:  IOVLsMod replaces the field ioVLsBkUp in ParamBlockRec. The name
  22824.        ioVLsBkUp was actually a misnomer; this field has always contained
  22825.        the date and time of the last modification, not the last backup.
  22826.        Another field, ioVBkUp, contains the date and time of the last backup.
  22827.  
  22828. IOVClpSiz can be used to set the volume clump size in bytes; it’s used for files that
  22829. don’t have a clump size defined as part of their file information in the catalog. To
  22830. promote file contiguity and avoid fragmentation, space is allocated to a file not in
  22831. allocation blocks but in clumps. A clump is a group of contiguous allocation blocks.
  22832. The clump size is always a multiple of the allocation block size; it’s the minimum
  22833. number of bytes to allocate each time the Allocate function is called or the end-of-file
  22834. is reached during the Write routine.
  22835.  
  22836. IOVSigWord contains a signature word identifying the type of volume; it’s $D2D7 for
  22837. flat directory volumes and $4244 for hierarchical directory volumes. The drive number
  22838. of the drive containing the volume is returned in ioDrvInfo. For on-line volumes,
  22839. ioVDRefNum returns the reference number of the I/O driver for the drive identified by
  22840. ioDrvInfo.
  22841.  
  22842. IOVFSID is the file-system identifier. It indicates which file system is servicing
  22843. the volume; it’s 0 for File Manager volumes and nonzero for volumes handled by an
  22844. external file system.
  22845.  
  22846. IOVBkUp specifies the date and time the volume was last backed up (it’s 0 if never
  22847. backed up).
  22848.  
  22849. IOVNmFls contains the number of files in the root directory. IOVFilCnt contains the
  22850. total number of files on the volume, while ioVDirCnt contains the total number of
  22851. directories (not including the root directory).
  22852.  
  22853. Most programmers needn’t be concerned with the other parameters, but interested
  22854. programmers can read the section “Data Organization on Volumes”.
  22855.  
  22856. HParamBlockRec, described above, has been extended to support a shared environment
  22857. with the addition of AccessParam, ObjParam, CopyParam, and
  22858. WDParam, as shown below.  (The complete HParamBlockRec data type is shown in the
  22859. summary.)
  22860.  
  22861.   AccessParam:
  22862.    (filler3:       INTEGER;
  22863.     ioDenyModes:   INTEGER;      {access rights data}
  22864.     filler4:       INTEGER;
  22865.     filler5:       Signed Byte;
  22866.     ioACUser:      Signed Byte;  {access rights for directory only}
  22867.     filler6:       LONGINT;
  22868.     ioACOwnerID:   LONGINT;      {owner ID}
  22869.     ioACGroupID:   LONGINT;      {group ID}
  22870.     ioACAccess:    LONGINT);     {access rights}
  22871.  
  22872.   ObjParam:
  22873.    (filler7:       INTEGER;
  22874.     ioObjType:     INTEGER;   {function code}
  22875.     ioObjNamePtr:  Ptr;       {ptr to returned creator/group name}
  22876.     ioObjID:       LONGINT;   {creator/group ID}
  22877.     ioReqCount:    LONGINT;   {size of buffer area}
  22878.     ioActCount:    LONGINT);  {length of vol parms data}
  22879.  
  22880.   CopyParam:
  22881.    (ioDstVRefNum:  INTEGER;   {destination vol identifier}
  22882.     filler8:       INTEGER;
  22883.     ioNewName:     Ptr;       {ptr to destination pathname}
  22884.     ioCopyName:    Ptr;       {ptr to optional name}
  22885.     ioNewDirID:    LONGINT);  {destination directory ID}
  22886.  
  22887.   WDParam:
  22888.    (filler9:       INTEGER;
  22889.     ioWDIndex:     INTEGER;
  22890.     ioWDProcID:    LONGINT;
  22891.     ioWDVRefNum:   INTEGER;
  22892.     filler10:      INTEGER;
  22893.     filler11:      LONGINT;
  22894.     filler12:      LONGINT;
  22895.     filler13:      LONGINT;
  22896.     ioWDDirID:     LONGINT);
  22897.  
  22898. æKY HFileInfo
  22899. æFc Files.h
  22900. æT struct
  22901. æD struct HFileInfo {
  22902.     ParamBlockHeader 
  22903.     short ioFRefNum;
  22904.     char ioFVersNum;
  22905.     char filler1;
  22906.     short ioFDirIndex;
  22907.     char ioFlAttrib;
  22908.     char filler2;
  22909.     FInfo ioFlFndrInfo;
  22910.     long ioDirID;
  22911.     unsigned short ioFlStBlk;
  22912.     long ioFlLgLen;
  22913.     long ioFlPyLen;
  22914.     unsigned short ioFlRStBlk;
  22915.     long ioFlRLgLen;
  22916.     long ioFlRPyLen;
  22917.     unsigned long ioFlCrDat;
  22918.     unsigned long ioFlMdDat;
  22919.     unsigned long ioFlBkDat;
  22920.     FXInfo ioFlXFndrInfo;
  22921.     long ioFlParID;
  22922.     long ioFlClpSiz;
  22923. };
  22924.  
  22925. typedef struct HFileInfo HFileInfo;
  22926. æC 
  22927.  
  22928. æKY DirInfo
  22929. æFc Files.h
  22930. æT struct
  22931. æD struct DirInfo {
  22932.     ParamBlockHeader 
  22933.     short ioFRefNum;
  22934.     short filler1;
  22935.     short ioFDirIndex;
  22936.     char ioFlAttrib;
  22937.     char filler2;
  22938.     DInfo ioDrUsrWds;
  22939.     long ioDrDirID;
  22940.     unsigned short ioDrNmFls;
  22941.     short filler3[9];
  22942.     unsigned long ioDrCrDat;
  22943.     unsigned long ioDrMdDat;
  22944.     unsigned long ioDrBkDat;
  22945.     DXInfo ioDrFndrInfo;
  22946.     long ioDrParID;
  22947. };
  22948.  
  22949. typedef struct DirInfo DirInfo;
  22950. æC 
  22951.  
  22952. æKY CInfoPBRec
  22953. CInfoPBPtr
  22954. æFc Files.h
  22955. æT struct
  22956. æD union CInfoPBRec {
  22957.     HFileInfo hFileInfo;
  22958.     DirInfo dirInfo;
  22959. };
  22960.  
  22961. typedef union CInfoPBRec CInfoPBRec;
  22962.  
  22963. typedef CInfoPBRec *CInfoPBPtr;
  22964.  
  22965. æC 
  22966. »CInfoPBRec
  22967.  
  22968. The routines GetCatInfo and SetCatInfo are used for getting and setting information
  22969. about the files and directories within a directory. With files,
  22970. you’ll use the following 19 additional fields after the standard eight fields in the
  22971. parameter block record CInfoPBRec:
  22972.  
  22973.     ioFRefNum:      INTEGER;     {path reference number}
  22974.     ioFVersNum:     SignedByte;  {version number}
  22975.     filler1:        SignedByte;  {not used}
  22976.     ioFDirIndex:    INTEGER;     {index}
  22977.     ioFlAttrib:     SignedByte;  {file attributes}
  22978.     filler2:        SignedByte;  {not used}
  22979.   hFileInfo:
  22980.    (ioFlFndrInfo:   FInfo;       {information used by the Finder}
  22981.     ioDirID:        LONGINT;     {directory ID or file number}
  22982.     ioFlStBlk:      INTEGER;     {first allocation block of data fork}
  22983.     ioFlLgLen:      LONGINT;     {logical end-of-file of data fork}
  22984.     ioFlPyLen:      LONGINT;     {physical end-of-file of data fork}
  22985.     ioFlRStBlk:     INTEGER;     {first allocation block of resource fork}
  22986.     ioFlRLgLen:     LONGINT;     {logical end-of-file of resource fork}
  22987.     ioFlRPyLen:     LONGINT;     {physical end-of-file of resource fork}
  22988.     ioFlCrDat:      LONGINT;     {date and time of creation}
  22989.     ioFlMdDat:      LONGINT;     {date and time of last modification}
  22990.     ioFlBkDat:      LONGINT;     {date and time of last backup}
  22991.     ioFlXFndrInfo:  FXInfo;      {additional information used by the Finder}
  22992.     ioFlParID:      LONGINT;     {file's parent directory ID (integer)}
  22993.     ioFlClpSiz:     LONGINT);    {file's clump size}
  22994.  
  22995. •••Refer to Technical Note #69:•••
  22996.  
  22997. IOFDirIndex can be used with the function PBGetCatInfo to index through the files and
  22998. directories in a given directory. For each iteration of the function, you can determine
  22999. whether it’s a file or a directory by testing bit 4 (the fifth least significant bit)
  23000. of ioFlAttrib. You can test for a directory by using the Toolbox Utilities BitTst
  23001. function in the following manner (remember, the Toolbox Utilities routines reverse
  23002. the standard 68000 notation):
  23003.  
  23004.   BitTst(@myCInfoRec.ioFlAttrib,3)
  23005.  
  23006. IOFlAttrib contains the following attributes:
  23007.  
  23008.   Bit    Meaning
  23009.  
  23010.    0     Set if file is locked
  23011.    2     Set if resource fork is open
  23012.    3     Set if data fork is open
  23013.    4     Set if a directory
  23014.    7     Set if file (either fork) is open
  23015.  
  23016. When passed to a routine, ioDirID contains a directory ID; it can be used to refer to
  23017. a directory or, in conjuction with a partial pathname from that directory, to other
  23018. files and directories. If both a directory ID and a working directory reference
  23019. number are provided, the directory ID is used to identify the directory on the volume
  23020. indicated by the working directory reference number. In other words, a directory ID
  23021. specified by the caller will override the working directory referred to by the working
  23022. directory reference number. If you don’t want this to happen, you can set ioDirID to
  23023. 0. (If no directory is specified through a working directory reference number, the
  23024. root directory ID will be used.)
  23025.  
  23026. Warning:  With files, ioDirID returns the file number of the file; when
  23027.           indexing with GetCatInfo, you’ll need to reset this field for
  23028.           each iteration.
  23029.  
  23030. IOFlStBlk and ioFlRStBlk contain 0 if the file’s data or resource fork is empty,
  23031. respectively; they’re used only with flat volumes. The date and time in the ioFlCrDat,
  23032. ioFlMdDat, and ioFlBkDat fields are specified in seconds since midnight, January 1,
  23033. 1904.
  23034.  
  23035. IOFlParID contains the directory ID of the file’s parent. IOFlClpSiz is the clump
  23036. size to be used when writing the file; if it’s 0, the volume’s clump size is used
  23037. when the file is opened.
  23038.  
  23039. With directories, you’ll use the following 14 additional fields after the standard
  23040. eight fields in the parameter block record CInfoPBRec:
  23041.  
  23042.     ioFRefNum:     INTEGER;     {file reference number}
  23043.     ioFVersNum     SignedByte;  {version number}
  23044.     filler1:       SignedByte;  {not used}
  23045.     ioFDirIndex:   INTEGER;     {index}
  23046.     ioFlAttrib:    SignedByte;  {file attributes}
  23047.     filler2:       SignedByte;  {not used}
  23048.   dirInfo:
  23049.    (ioDrUsrWds:    DInfo;       {information used by the Finder}
  23050.     ioDrDirID:     LONGINT;     {directory ID}
  23051.     ioDrNmFls:     INTEGER;     {number of files in directory}
  23052.     filler3:       ARRAY[1..9] OF INTEGER; {not used}
  23053.     ioDrCrDat:     LONGINT;     {date and time of creation}
  23054.     ioDrMdDat:     LONGINT;     {date and time of last modification}
  23055.     ioDrBkDat:     LONGINT;     {date and time of last backup}
  23056.     ioDrFndrInfo:  DXInfo;      {additional information used by the Finder}
  23057.     ioDrParID:     LONGINT);    {directory's parent directory ID (integer)}
  23058.  
  23059. IOFDirIndex can be used with the function PBGetCatInfo to index through the files and
  23060. directories in a given directory. For each iteration of the function, you can determine
  23061. whether it’s a file or a directory by testing bit 4 of ioFlAttrib.
  23062.  
  23063. When passed to a routine, ioDrDirID contains a directory ID; it can be used to refer
  23064. to a directory or, in conjuction with a partial pathname from that directory, to
  23065. other files and directories. If both a directory ID and a working directory reference
  23066. number are provided, the directory ID is used to identify the directory on the volume
  23067. indicated by the working directory reference number. In other words, a directory ID
  23068. specified by the caller will override the working directory referred to by the working
  23069. directory reference number. If you don’t want this to happen, you can set ioDirID to
  23070. 0. (If no directory is specified through a working directory reference number, the
  23071. root directory ID will be used.)
  23072.  
  23073. With directories, ioDrDirID returns the directory ID of the directory.
  23074.  
  23075. IODrNmFls is the number of files and directories contained in this directory
  23076. (the valence of the directory).
  23077.  
  23078. The date and time in the ioDrCrDat, ioDrMdDat, and ioDrBkDat fields are specified in
  23079. seconds since midnight, January 1, 1904.
  23080.  
  23081. IODrParID contains the directory ID of the directory’s parent.
  23082.  
  23083. æKY HIOParam
  23084. æFc Files.h
  23085. æT struct
  23086. æD struct HIOParam {
  23087.     ParamBlockHeader 
  23088.     short ioRefNum;
  23089.     char ioVersNum;
  23090.     char ioPermssn;
  23091.     Ptr ioMisc;
  23092.     Ptr ioBuffer;
  23093.     long ioReqCount;
  23094.     long ioActCount;
  23095.     short ioPosMode;
  23096.     long ioPosOffset;
  23097.     short filler1;
  23098. };
  23099.  
  23100. typedef struct HIOParam HIOParam;
  23101. æC 
  23102.  
  23103. æKY HFileParam
  23104. æFc Files.h
  23105. æT struct
  23106. æD struct HFileParam {
  23107.     ParamBlockHeader 
  23108.     short ioFRefNum;
  23109.     char ioFVersNum;
  23110.     char filler1;
  23111.     short ioFDirIndex;
  23112.     char ioFlAttrib;
  23113.     char ioFlVersNum;
  23114.     FInfo ioFlFndrInfo;
  23115.     long ioDirID;
  23116.     unsigned short ioFlStBlk;
  23117.     long ioFlLgLen;
  23118.     long ioFlPyLen;
  23119.     unsigned short ioFlRStBlk;
  23120.     long ioFlRLgLen;
  23121.     long ioFlRPyLen;
  23122.     unsigned long ioFlCrDat;
  23123.     unsigned long ioFlMdDat;
  23124. };
  23125.  
  23126. typedef struct HFileParam HFileParam;
  23127. æC 
  23128.  
  23129. æKY HVolumeParam
  23130. æFc Files.h
  23131. æT struct
  23132. æD struct HVolumeParam {
  23133.     ParamBlockHeader 
  23134.     long filler2;
  23135.     short ioVolIndex;
  23136.     unsigned long ioVCrDate;
  23137.     unsigned long ioVLsMod;
  23138.     short ioVAtrb;
  23139.     unsigned short ioVNmFls;
  23140.     short ioVBitMap;
  23141.     short ioAllocPtr;
  23142.     unsigned short ioVNmAlBlks;
  23143.     long ioVAlBlkSiz;
  23144.     long ioVClpSiz;
  23145.     short ioAlBlSt;
  23146.     long ioVNxtCNID;
  23147.     unsigned short ioVFrBlk;
  23148.     unsigned short ioVSigWord;
  23149.     short ioVDrvInfo;
  23150.     short ioVDRefNum;
  23151.     short ioVFSID;
  23152.     unsigned long ioVBkUp;
  23153.     unsigned short ioVSeqNum;
  23154.     long ioVWrCnt;
  23155.     long ioVFilCnt;
  23156.     long ioVDirCnt;
  23157.     long ioVFndrInfo[8];
  23158. };
  23159.  
  23160. typedef struct HVolumeParam HVolumeParam;
  23161. æC 
  23162.  
  23163. æKY AccessParam
  23164. æFc Files.h
  23165. æT struct
  23166. æD struct AccessParam {
  23167.     ParamBlockHeader 
  23168.     short filler3;
  23169.     short ioDenyModes; /*access rights data*/
  23170.     short filler4;
  23171.     char filler5;
  23172.     char ioACUser; /*access rights for directory only*/
  23173.     long filler6;
  23174.     long ioACOwnerID; /*owner ID*/
  23175.     long ioACGroupID; /*group ID*/
  23176.     long ioACAccess; /*access rights*/
  23177. };
  23178.  
  23179. typedef struct AccessParam AccessParam;
  23180. æC 
  23181.  
  23182. æKY ObjParam
  23183. æFc Files.h
  23184. æT struct
  23185. æD struct ObjParam {
  23186.     ParamBlockHeader 
  23187.     short filler7;
  23188.     short ioObjType; /*function code*/
  23189.     Ptr ioObjNamePtr; /*ptr to returned creator/group name*/
  23190.     long ioObjID; /*creator/group ID*/
  23191.     long ioReqCount; /*size of buffer area*/
  23192.     long ioActCount; /*length of vol parms data*/
  23193. };
  23194.  
  23195. typedef struct ObjParam ObjParam;
  23196. æC 
  23197.  
  23198. æKY CopyParam
  23199. æFc Files.h
  23200. æT struct
  23201. æD struct CopyParam {
  23202.     ParamBlockHeader 
  23203.     short ioDstVRefNum; /*destination vol identifier*/
  23204.     short filler8;
  23205.     Ptr ioNewName; /*ptr to destination pathname*/
  23206.     Ptr ioCopyName; /*ptr to optional name*/
  23207.     long ioNewDirID; /*destination directory ID*/
  23208.     long filler14;
  23209.     long filler15;
  23210.     long ioDirID; /*same as in FileParam*/
  23211. };
  23212.  
  23213. typedef struct CopyParam CopyParam;
  23214. æC 
  23215.  
  23216. æKY WDParam
  23217. æFc Files.h
  23218. æT struct
  23219. æD struct WDParam {
  23220.     ParamBlockHeader 
  23221.     short filler9;
  23222.     short ioWDIndex;
  23223.     long ioWDProcID;
  23224.     short ioWDVRefNum;
  23225.     short filler10;
  23226.     long filler11;
  23227.     long filler12;
  23228.     long filler13;
  23229.     long ioWDDirID;
  23230. };
  23231.  
  23232. typedef struct WDParam WDParam;
  23233. æC 
  23234.  
  23235. æKY FIDParam
  23236. æFc Files.h
  23237. æT struct
  23238. æD struct FIDParam {
  23239.     ParamBlockHeader 
  23240.     long filler1;
  23241.     Ptr ioDestNamePtr; /* dest file name */
  23242.     long filler2;
  23243.     long ioDestDirID; /* dest file's directory id */
  23244.     long filler3;
  23245.     long filler4;
  23246.     long ioSrcDirID; /* source file's directory id */
  23247.     short filler5;
  23248.     long ioFileID; /* file ID */
  23249. };
  23250.  
  23251. typedef struct FIDParam FIDParam;
  23252. /*  Catalog position record  */
  23253. æC 
  23254.  
  23255. æKY CatPositionRec
  23256. æFc Files.h
  23257. æT struct
  23258. æD struct CatPositionRec {
  23259.     long initialize;
  23260.     short priv[6];
  23261. };
  23262.  
  23263. typedef struct CatPositionRec CatPositionRec;
  23264. æC 
  23265.  
  23266. æKY FSSpec
  23267. FSSpecPtr
  23268. FSSpecHandle
  23269. æFc Files.h
  23270. æT struct
  23271. æD struct FSSpec {
  23272.     short vRefNum;
  23273.     long parID;
  23274.     Str63 name;
  23275. };
  23276.  
  23277. typedef struct FSSpec FSSpec;
  23278. typedef FSSpec *FSSpecPtr, **FSSpecHandle;
  23279.  
  23280. æC 
  23281.  
  23282. æKY CSParam
  23283. CSParamPtr
  23284. æFc Files.h
  23285. æT struct
  23286. æD struct CSParam {
  23287.     ParamBlockHeader 
  23288.     FSSpecPtr ioMatchPtr; /* match array */
  23289.     long ioReqMatchCount; /* maximum allowable matches */
  23290.     long ioActMatchCount; /* actual match count */
  23291.     long ioSpecBits; /* search criteria selector */
  23292.     CInfoPBPtr ioSpec1; /* search values and range lower bounds */
  23293.     CInfoPBPtr ioSpec2; /* search values and range upper bounds */
  23294.     long ioSearchTime; /* length of time to run search */
  23295.     CatPositionRec ioCatPosition; /* current position in the catalog */
  23296.     Ptr ioOptBuffer; /* optional performance enhancement buffer */
  23297.     long ioOptBufSize; /* size of buffer pointed to by ioOptBuffer */
  23298. };
  23299.  
  23300. typedef struct CSParam CSParam;
  23301. typedef CSParam *CSParamPtr;
  23302.  
  23303. æC 
  23304.  
  23305. æKY DTPBRec
  23306. DTPBPtr
  23307. æFc Files.h
  23308. æT struct
  23309. æD struct DTPBRec {
  23310.     ParamBlockHeader 
  23311.     short ioDTRefNum; /* desktop refnum */
  23312.     short ioIndex;
  23313.     long ioTagInfo;
  23314.     Ptr ioDTBuffer;
  23315.     long ioDTReqCount;
  23316.     long ioDTActCount;
  23317.     char ioFiller1;
  23318.     char ioIconType;
  23319.     short ioFiller2;
  23320.     long ioDirID;
  23321.     OSType ioFileCreator;
  23322.     OSType ioFileType;
  23323.     long ioFiller3;
  23324.     long ioDTLgLen;
  23325.     long ioDTPyLen;
  23326.     short ioFiller4[14];
  23327.     long ioAPPLParID;
  23328. };
  23329.  
  23330. typedef struct DTPBRec DTPBRec;
  23331. typedef DTPBRec *DTPBPtr;
  23332.  
  23333. æC 
  23334.  
  23335. æKY AltAccessParam
  23336. AltAccessParamPtr
  23337. æFc Files.h
  23338. æT struct
  23339. æD struct AltAccessParam {
  23340.     ParamBlockHeader 
  23341.     long ioFiller1;
  23342.     long ioFiller2;
  23343.     Ptr ioAltAccessBuffer;
  23344.     long ioAltReqCount;
  23345.     long ioAltActCount;
  23346.     long ioAltAccessInfo1;
  23347.     long ioAltAccessInfo2;
  23348.     long ioAltAccessInfo3;
  23349.     long ioAltAccessInfo4;
  23350. };
  23351.  
  23352. typedef struct AltAccessParam AltAccessParam;
  23353. typedef AltAccessParam *AltAccessParamPtr;
  23354.  
  23355. æC 
  23356.  
  23357. æKY HParamBlockRec
  23358. HParmBlkPtr
  23359. æFc Files.h
  23360. æT struct
  23361. æD union HParamBlockRec {
  23362.     HIOParam ioParam;
  23363.     HFileParam fileParam;
  23364.     HVolumeParam volumeParam;
  23365.     AccessParam accessParam;
  23366.     ObjParam objParam;
  23367.     CopyParam copyParam;
  23368.     WDParam wdParam;
  23369.     FIDParam fidParam;
  23370.     CSParam csParam;
  23371.     AltAccessParam altaccessParam;
  23372. };
  23373.  
  23374. typedef union HParamBlockRec HParamBlockRec;
  23375.  
  23376. typedef HParamBlockRec *HParmBlkPtr;
  23377.  
  23378. æC »FileParam Variant ( ParamBlockRec and HParamBlockRec)
  23379.  
  23380. The fileParam variants of ParamBlockRec and HParamBlockRec are identical, with one
  23381. exception:  The field ioDirID in HParamBlockRec is called ioFlNum in ParamBlockRec.
  23382. The fields of the fileParam variant of HParamBlockRec are as follows:  
  23383.  
  23384. •••Refer to Technical Note #204:•••
  23385.  
  23386.   fileParam:
  23387.    (ioFRefNum:     INTEGER;     {path reference number}
  23388.     ioFVersNum:    SignedByte;  {version number}
  23389.     filler1:       SignedByte;  {not used}
  23390.     ioFDirIndex:   INTEGER;     {index}
  23391.     ioFlAttrib:    SignedByte;  {file attributes}
  23392.     ioFlVersNum:   SignedByte;  {version number}
  23393.     ioFlFndrInfo:  FInfo;       {information used by the Finder}
  23394.     ioDirID:       LONGINT;     {directory ID or file number}
  23395.     ioFlStBlk:     INTEGER;     {first allocation block of data fork}
  23396.     ioFlLgLen:     LONGINT;     {logical end-of-file of data fork}
  23397.     ioFlPyLen:     LONGINT;     {physical end-of-file of data fork}
  23398.     ioFlRStBlk:    INTEGER;     {first allocation block of resource fork}
  23399.     ioFlRLgLen:    LONGINT;     {logical end-of-file of resource fork}
  23400.     ioFlRPyLen:    LONGINT;     {physical end-of-file of resource fork}
  23401.     ioFlCrDat:     LONGINT;     {date and time of creation}
  23402.     ioFlMdDat:     LONGINT);    {date and time of last modification}
  23403.  
  23404. IOFDirIndex can be used with the PBGetFInfo and PBHGetFInfo to index through the
  23405. files in a given directory.
  23406.  
  23407. Warning:  When used with GetFileInfo, ioFDirIndex will index only the files
  23408.           in a directory. To index both files and directories, you can use
  23409.           ioFDirIndex with PBGetCatInfo.
  23410.  
  23411. IOFlAttrib contains the following file attributes:
  23412.  
  23413.   Bit    Meaning
  23414.  
  23415.    0     Set if file is locked
  23416.    2     Set if resource fork is open
  23417.    3     Set if data fork is open
  23418.    4     Set if a directory
  23419.    7     Set if file (either fork) is open
  23420.  
  23421. When passed to a routine, ioDirID contains a directory ID; it can be used to refer to
  23422. a directory or, in conjuction with a partial pathname from that directory, to other
  23423. files and directories. If both a directory ID and a working directory reference
  23424. number are provided, the directory ID is used to identify the directory on the volume
  23425. indicated by the working directory reference number. In other words, a directory ID
  23426. specified by the caller will override the working directory referred to by the working
  23427. directory reference number. If you don’t want this to happen, you can set ioDirID to
  23428. 0. (If no directory is specified through a working directory reference number, the
  23429. root directory ID will be used.)
  23430.  
  23431. When returned from a routine, ioDirID contains the file number of a file; most programmers
  23432. needn’t be concerned with file numbers, but those interested can read the section
  23433. “Data Organization on Volumes”.
  23434.  
  23435. IOFlStBlk and ioFlRStBlk contain 0 if the file’s data or resource fork is empty,
  23436. respectively; they’re used only with flat volumes. The date and time in the ioFlCrDat
  23437. and ioFlMdDat fields are specified in seconds since midnight,
  23438. January 1, 1904.
  23439.  
  23440. »VolumeParam Variant (ParamBlockRec)
  23441.  
  23442. When you call GetVolInfo, you’ll use the volumeParam variant of ParamBlockRec:
  23443.  
  23444.   volumeParam:
  23445.    (filler2:      LONGINT;    {not used}
  23446.     ioVolIndex:   INTEGER;    {index}
  23447.     ioVCrDate:    LONGINT;    {date and time of initialization}
  23448.     ioVLsBkUp:    LONGINT;    {date and time of last modification}
  23449.     ioVAtrb:      INTEGER;    {volume attributes}
  23450.     ioVNmFls:     INTEGER;    {number of files in root directory}
  23451.     ioVDirSt:     INTEGER;    {first block of directory}
  23452.     ioVBlLn:      INTEGER;    {length of directory in blocks}
  23453.     ioVNmAlBlks:  INTEGER;    {number of allocation blocks}
  23454.     ioVAlBlkSiz:  LONGINT;    {size of allocation blocks}
  23455.     ioVClpSiz:    LONGINT;    {number of bytes to allocate}
  23456.     ioAlBlSt:     INTEGER;    {first block in volume block map}
  23457.     ioVNxtFNum:   LONGINT;    {next unused file number}
  23458.     ioVFrBlk:     INTEGER);   {number of unused allocation blocks}
  23459.  
  23460. IOVolIndex can be used to index through all the mounted volumes; using an index of 1
  23461. accesses the first volume mounted, and so on. (For more information on indexing, see
  23462. the section “Indexing” above.)
  23463.  
  23464. IOVLsBkUp contains the date and time the volume information was last modified
  23465. (this is not necessarily when it was flushed). (This field is not modified when
  23466. information is written to a file.)
  23467.  
  23468. Note:  The name ioVLsBkUp is actually a misnomer; this field has always
  23469.        contained the date and time of the last modification to the volume,
  23470.        not the last backup.
  23471.  
  23472. Most programmers needn’t be concerned with the remaining parameters, but interested
  23473. programmers can read the section “Data Organization on Volumes”.
  23474.  
  23475. »VolumeParam Variant (HParamBlockRec)
  23476.  
  23477. When you call HGetVInfo and SetVolInfo, you’ll use the volumeParam variant of HParamBlockRec.
  23478. This is a superset of the volumeParam variant of ParamBlockRec; the names and functions
  23479. of certain fields have been changed, and new fields have been added:
  23480.  
  23481.   volumeParam:
  23482.    (filler2:      LONGINT;    {not used}
  23483.     ioVolIndex:   INTEGER;    {index}
  23484.     ioVCrDate:    LONGINT;    {date and time of initialization}
  23485.     ioVLsMod:     LONGINT;    {date and time of last modification}
  23486.     ioVAtrb:      INTEGER;    {volume attributes}
  23487.     ioVNmFls:     INTEGER;    {number of files in root directory}
  23488.     ioVBitMap:    INTEGER;    {first block of volume bit map}
  23489.     ioAllocPtr:   INTEGER;    {block at which next new file starts}
  23490.     ioVNmAlBlks:  INTEGER;    {number of allocation blocks}
  23491.     ioVAlBlkSiz:  LONGINT;    {size of allocation blocks}
  23492.     ioVClpSiz:    LONGINT;    {number of bytes to allocate}
  23493.     ioAlBlSt:     INTEGER;    {first block in volume block map}
  23494.     ioVNxtCNID:   LONGINT;    {next unused file number}
  23495.     ioVFrBlk:     INTEGER;    {number of unused allocation blocks}
  23496.     ioVSigWord:   INTEGER;    {volume signature}
  23497.     ioVDrvInfo:   INTEGER;    {drive number}
  23498.     ioVDRefNum:   INTEGER;    {driver reference number}
  23499.     ioVFSID:      INTEGER;    {file system handling this volume}
  23500.     ioVBkUp:      LONGINT;    {date and time of last backup}
  23501.     ioVSeqNum:    INTEGER;    {used internally}
  23502.     ioVWrCnt      LONGINT;    {volume write count}
  23503.     ioVFilCnt:    LONGINT;    {number of files on volume}
  23504.     ioVDirCnt:    LONGINT;    {number of directories on volume}
  23505.     ioVFndrInfo:  ARRAY[1..8] OF LONGINT); {information used by the Finder}
  23506.  
  23507. IOVolIndex can be used to index through all the mounted volumes; using an index of 1
  23508. accesses the first volume mounted, and so on. (For more information on indexing, see
  23509. the section “Indexing” above.)
  23510.  
  23511. IOVLsMod contains the date and time the volume information was last modified
  23512. (this is not necessarily when it was flushed). (This field is not modified when
  23513. information is written to a file.)
  23514.  
  23515. Note:  IOVLsMod replaces the field ioVLsBkUp in ParamBlockRec. The name
  23516.        ioVLsBkUp was actually a misnomer; this field has always contained
  23517.        the date and time of the last modification, not the last backup.
  23518.        Another field, ioVBkUp, contains the date and time of the last backup.
  23519.  
  23520. IOVClpSiz can be used to set the volume clump size in bytes; it’s used for files that
  23521. don’t have a clump size defined as part of their file information in the catalog. To
  23522. promote file contiguity and avoid fragmentation, space is allocated to a file not in
  23523. allocation blocks but in clumps. A clump is a group of contiguous allocation blocks.
  23524. The clump size is always a multiple of the allocation block size; it’s the minimum
  23525. number of bytes to allocate each time the Allocate function is called or the end-of-file
  23526. is reached during the Write routine.
  23527.  
  23528. IOVSigWord contains a signature word identifying the type of volume; it’s $D2D7 for
  23529. flat directory volumes and $4244 for hierarchical directory volumes. The drive number
  23530. of the drive containing the volume is returned in ioDrvInfo. For on-line volumes,
  23531. ioVDRefNum returns the reference number of the I/O driver for the drive identified by
  23532. ioDrvInfo.
  23533.  
  23534. IOVFSID is the file-system identifier. It indicates which file system is servicing
  23535. the volume; it’s 0 for File Manager volumes and nonzero for volumes handled by an
  23536. external file system.
  23537.  
  23538. IOVBkUp specifies the date and time the volume was last backed up (it’s 0 if never
  23539. backed up).
  23540.  
  23541. IOVNmFls contains the number of files in the root directory. IOVFilCnt contains the
  23542. total number of files on the volume, while ioVDirCnt contains the total number of
  23543. directories (not including the root directory).
  23544.  
  23545. Most programmers needn’t be concerned with the other parameters, but interested
  23546. programmers can read the section “Data Organization on Volumes”.
  23547.  
  23548. HParamBlockRec, described above, has been extended to support a shared environment
  23549. with the addition of AccessParam, ObjParam, CopyParam, and
  23550. WDParam, as shown below.  (The complete HParamBlockRec data type is shown in the
  23551. summary.)
  23552.  
  23553.   AccessParam:
  23554.    (filler3:       INTEGER;
  23555.     ioDenyModes:   INTEGER;      {access rights data}
  23556.     filler4:       INTEGER;
  23557.     filler5:       Signed Byte;
  23558.     ioACUser:      Signed Byte;  {access rights for directory only}
  23559.     filler6:       LONGINT;
  23560.     ioACOwnerID:   LONGINT;      {owner ID}
  23561.     ioACGroupID:   LONGINT;      {group ID}
  23562.     ioACAccess:    LONGINT);     {access rights}
  23563.  
  23564.   ObjParam:
  23565.    (filler7:       INTEGER;
  23566.     ioObjType:     INTEGER;   {function code}
  23567.     ioObjNamePtr:  Ptr;       {ptr to returned creator/group name}
  23568.     ioObjID:       LONGINT;   {creator/group ID}
  23569.     ioReqCount:    LONGINT;   {size of buffer area}
  23570.     ioActCount:    LONGINT);  {length of vol parms data}
  23571.  
  23572.   CopyParam:
  23573.    (ioDstVRefNum:  INTEGER;   {destination vol identifier}
  23574.     filler8:       INTEGER;
  23575.     ioNewName:     Ptr;       {ptr to destination pathname}
  23576.     ioCopyName:    Ptr;       {ptr to optional name}
  23577.     ioNewDirID:    LONGINT);  {destination directory ID}
  23578.  
  23579.   WDParam:
  23580.    (filler9:       INTEGER;
  23581.     ioWDIndex:     INTEGER;
  23582.     ioWDProcID:    LONGINT;
  23583.     ioWDVRefNum:   INTEGER;
  23584.     filler10:      INTEGER;
  23585.     filler11:      LONGINT;
  23586.     filler12:      LONGINT;
  23587.     filler13:      LONGINT;
  23588.     ioWDDirID:     LONGINT);
  23589.  
  23590. æKY CMovePBRec
  23591. CMovePBPtr
  23592. æFc Files.h
  23593. æT struct
  23594. æD struct CMovePBRec {
  23595.     QElemPtr qLink;
  23596.     short qType;
  23597.     short ioTrap;
  23598.     Ptr ioCmdAddr;
  23599.     ProcPtr ioCompletion;
  23600.     OSErr ioResult;
  23601.     StringPtr ioNamePtr;
  23602.     short ioVRefNum;
  23603.     long filler1;
  23604.     StringPtr ioNewName;
  23605.     long filler2;
  23606.     long ioNewDirID;
  23607.     long filler3[2];
  23608.     long ioDirID;
  23609. };
  23610.  
  23611. typedef struct CMovePBRec CMovePBRec;
  23612. typedef CMovePBRec *CMovePBPtr;
  23613.  
  23614. æC 
  23615.  
  23616. »CMovePBRec
  23617.  
  23618. When you call CatMove to move files or directories into a different directory, you’ll
  23619. use the following six additional fields after the standard eight fields in the parameter
  23620. block record CMovePBRec:
  23621.  
  23622.   filler1:     LONGINT;    {not used}
  23623.   ioNewName:   StringPtr;  {name of new directory}
  23624.   filler2:     LONGINT;    {not used}
  23625.   ioNewDirID:  LONGINT;    {directory ID of new directory}
  23626.   filler3:     ARRAY[1..2] OF LONGINT; {not used}
  23627.   ioDirID:     LONGINT);   {directory ID of current directory}
  23628.  
  23629. IONewName and ioNewDirID specify the name and directory ID of the directory to which
  23630. the file or directory is to be moved. IODirID (used in conjuntion with the ioVRefNum
  23631. and ioNamePtr) specifies the current directory ID of the file or directory to be
  23632. moved.
  23633.  
  23634. æKY WDPBRec
  23635. WDPBPtr
  23636. æFc Files.h
  23637. æT struct
  23638. æD struct WDPBRec {
  23639.     QElemPtr qLink;
  23640.     short qType;
  23641.     short ioTrap;
  23642.     Ptr ioCmdAddr;
  23643.     ProcPtr ioCompletion;
  23644.     OSErr ioResult;
  23645.     StringPtr ioNamePtr;
  23646.     short ioVRefNum;
  23647.     short filler1;
  23648.     short ioWDIndex;
  23649.     long ioWDProcID;
  23650.     short ioWDVRefNum;
  23651.     short filler2[7];
  23652.     long ioWDDirID;
  23653. };
  23654.  
  23655. typedef struct WDPBRec WDPBRec;
  23656. typedef WDPBRec *WDPBPtr;
  23657.  
  23658. æC 
  23659.  
  23660. »WDPBRec
  23661.  
  23662. When you call the routines that open, close, and get information about working directories,
  23663. you’ll use the following six additional fields after the standard eight fields in the
  23664. parameter block record WDPBRec:
  23665.  
  23666.   filler1:      INTEGER;    {not used}
  23667.   ioWDIndex:    INTEGER;    {index}
  23668.   ioWDProcID:   LONGINT;    {working directory user identifier}
  23669.   ioWDVRefNum:  INTEGER;    {working directory's volume reference number}
  23670.   filler2:      ARRAY[1..7] OF INTEGER;  {not used}
  23671.   ioWDDirID:    LONGINT);   {working directory's directory ID}
  23672.  
  23673. IOWDIndex can be used with the function PBGetWDInfo to index through the current
  23674. working directories.
  23675.  
  23676. IOWDProcID is an identifier that’s used to distinguish between working directories
  23677. set up by different users; you should use the application’s signature (discussed in
  23678. the Finder Interface chapter) as the ioWDProcID.
  23679.  
  23680. æKY FCBPBRec
  23681. FCBPBPtr
  23682. æFc Files.h
  23683. æT struct
  23684. æD struct FCBPBRec {
  23685.     QElemPtr qLink;
  23686.     short qType;
  23687.     short ioTrap;
  23688.     Ptr ioCmdAddr;
  23689.     ProcPtr ioCompletion;
  23690.     OSErr ioResult;
  23691.     StringPtr ioNamePtr;
  23692.     short ioVRefNum;
  23693.     short ioRefNum;
  23694.     short filler;
  23695.     short ioFCBIndx;
  23696.     short filler1;
  23697.     long ioFCBFlNm;
  23698.     short ioFCBFlags;
  23699.     unsigned short ioFCBStBlk;
  23700.     long ioFCBEOF;
  23701.     long ioFCBPLen;
  23702.     long ioFCBCrPs;
  23703.     short ioFCBVRefNum;
  23704.     long ioFCBClpSiz;
  23705.     long ioFCBParID;
  23706. };
  23707.  
  23708. typedef struct FCBPBRec FCBPBRec;
  23709. typedef FCBPBRec *FCBPBPtr;
  23710.  
  23711. æC 
  23712.  
  23713. æKY VCB
  23714. æFc Files.h
  23715. æT struct
  23716. æD struct VCB {
  23717.     QElemPtr qLink;
  23718.     short qType;
  23719.     short vcbFlags;
  23720.     unsigned short vcbSigWord;
  23721.     unsigned long vcbCrDate;
  23722.     unsigned long vcbLsMod;
  23723.     short vcbAtrb;
  23724.     unsigned short vcbNmFls;
  23725.     short vcbVBMSt;
  23726.     short vcbAllocPtr;
  23727.     unsigned short vcbNmAlBlks;
  23728.     long vcbAlBlkSiz;
  23729.     long vcbClpSiz;
  23730.     short vcbAlBlSt;
  23731.     long vcbNxtCNID;
  23732.     unsigned short vcbFreeBks;
  23733.     Str27 vcbVN;
  23734.     short vcbDrvNum;
  23735.     short vcbDRefNum;
  23736.     short vcbFSID;
  23737.     short vcbVRefNum;
  23738.     Ptr vcbMAdr;
  23739.     Ptr vcbBufAdr;
  23740.     short vcbMLen;
  23741.     short vcbDirIndex;
  23742.     short vcbDirBlk;
  23743.     unsigned long vcbVolBkUp;
  23744.     unsigned short vcbVSeqNum;
  23745.     long vcbWrCnt;
  23746.     long vcbXTClpSiz;
  23747.     long vcbCTClpSiz;
  23748.     unsigned short vcbNmRtDirs;
  23749.     long vcbFilCnt;
  23750.     long vcbDirCnt;
  23751.     long vcbFndrInfo[8];
  23752.     unsigned short vcbVCSize;
  23753.     unsigned short vcbVBMCSiz;
  23754.     unsigned short vcbCtlCSiz;
  23755.     unsigned short vcbXTAlBlks;
  23756.     unsigned short vcbCTAlBlks;
  23757.     short vcbXTRef;
  23758.     short vcbCTRef;
  23759.     Ptr vcbCtlBuf;
  23760.     long vcbDirIDM;
  23761.     short vcbOffsM;
  23762. };
  23763.  
  23764. typedef struct VCB VCB;
  23765. æC 
  23766. »Volume Control Blocks
  23767.  
  23768. •••Refer to Technical Note #106:•••
  23769.  
  23770. Each time a volume is mounted, its volume information is read from it and is used to
  23771. build a new volume control block in the volume-control-block queue
  23772. (unless an ejected or off-line volume is being remounted). A copy of the volume block
  23773. map is also read from the volume and placed in the system heap, and a volume buffer
  23774. is created in the system heap.
  23775.  
  23776. The volume-control-block queue is a standard Operating System queue that’s maintained
  23777. in the system heap. It contains a volume control block for each mounted volume. A
  23778. volume control block is a 178-byte nonrelocatable block that contains volume-specific
  23779. information. It has the following structure:
  23780.  
  23781. TYPE VCB = RECORD
  23782.              qLink:        QElemPtr;   {next queue entry}
  23783.              qType:        INTEGER;    {queue type}
  23784.              vcbFlags:     INTEGER;    {bit 15=1 if dirty}
  23785.              vcbSigWord:   INTEGER;    {$4244 for hierarchical, $D2D7 for flat}
  23786.              vcbCrDate:    LONGINT;    {date and time of initialization}
  23787.              vcbLsMod:     LONGINT;    {date and time of last modification}
  23788.              vcbAtrb:      INTEGER;    {volume attributes}
  23789.              vcbNmFls:     INTEGER;    {number of files in directory}
  23790.              vcbVBMSt:     INTEGER;    {first block of volume bit map}
  23791.              vcbAllocPtr:  INTEGER;    {used internally}
  23792.              vcbNmAlBlks:  INTEGER;    {number of allocation blocks}
  23793.              vcbAlBlkSiz:  LONGINT;    {allocation block size}
  23794.              vcbClpSiz:    LONGINT;    {default clump size}
  23795.              vcbAlBlSt:    INTEGER;    {first block in block map}
  23796.              vcbNxtCNID:   LONGINT;    {next unused directory ID or file number}
  23797.              vcbFreeBks:   INTEGER;    {number of unused allocation blocks}
  23798.              vcbVN:        STRING[27]; {volume name}
  23799.              vcbDrvNum:    INTEGER;    {drive number}
  23800.              vcbDRefNum:   INTEGER;    {driver reference number}
  23801.              vcbFSID:      INTEGER;    {file-system identifier}
  23802.              vcbVRefNum:   INTEGER;    {volume reference number}
  23803.              vcbMAdr:      Ptr;        {pointer to block map}
  23804.              vcbBufAdr:    Ptr;        {pointer to volume buffer}
  23805.              vcbMLen:      INTEGER;    {number of bytes in block map}
  23806.              vcbDirIndex:  INTEGER;    {used internally}
  23807.              vcbDirBlk:    INTEGER;    {used internally}
  23808.              vcbVolBkUp:   LONGINT;    {date and time of last backup}
  23809.              vcbVSeqNum:   INTEGER;    {used internally}
  23810.              vcbWrCnt:     LONGINT;    {volume write count}
  23811.              vcbXTClpSiz:  LONGINT;    {clump size of extents tree file}
  23812.              vcbCTClpSiz:  LONGINT;    {clump size of catalog tree file}
  23813.              vcbNmRtDirs:  INTEGER;    {number of directories in root}
  23814.              vcbFilCnt:    LONGINT;    {number of files on volume}
  23815.              vcbDirCnt:    LONGINT;    {number of directories on volume}
  23816.              vcbFndrInfo:  ARRAY[1..8] OF LONGINT;  {information used by }
  23817.                                                     { the Finder}
  23818.              vcbVCSize:    INTEGER;    {used internally}
  23819.              vcbVBMCSiz:   INTEGER;    {used internally}
  23820.              vcbCtlCSiz:   INTEGER;    {used internally}
  23821.              vcbXTAlBks:   INTEGER;    {size in blocks of extents tree file}
  23822.              vcbCTAlBks:   INTEGER;    {size in blocks of catalog tree file}
  23823.              vcbXTRef:     INTEGER;    {path reference number for extents }
  23824.                                        { tree file}
  23825.              vcbCTRef:     INTEGER;    {path reference number for catalog }
  23826.                                        { tree file}
  23827.              vcbCtlBuf:    Ptr;        {pointer to extents and catalog }
  23828.                                        { tree caches}
  23829.              vcbDirIDM:    LONGINT;    {directory last searched}
  23830.              vcbOffsM:     INTEGER     {offspring index at last search}
  23831.            END;
  23832.  
  23833. 64K ROM note:  A volume control block created for a flat volume is a subset
  23834.                of the above structure. It’s actually smaller and contains
  23835.                only the fields up to and including vcbDirBlk. In addition,
  23836.                the names of several fields have been changed to reflect the
  23837.                fact that they contain different information on hierarchical
  23838.                volumes:  vcbLsBkUp, vcbDirSt, vcbBlLn, vcbNmBlks, and
  23839.                vcbNxtFNum have been changed to vcbLsMod, vcbVBMSt,
  23840.                vcbAllocPtr, vcbNmAlBlks, and vcbNxtCNID respectively.
  23841.  
  23842. QLink points to the next entry in the queue, and qType indicates the queue type,
  23843. which must always be ORD(fsQType). Bit 15 of vcbFlags is set if the volume information
  23844. has been changed by a routine call since the volume was last affected by a FlushVol
  23845. call.
  23846.  
  23847. VCBLsMod contains the date and time that the volume was last modified (this is not
  23848. necessarily when it was flushed).
  23849.  
  23850. 64K ROM note:  VCBLsMod replaces the field vcbLsBkUp from flat directory
  23851.                volumes. The name vcbLsBkUp was actually a misnomer; this
  23852.                field has always contained the date and time of the last
  23853.                modification, not the last backup. Another field, vcbVolBkUp,
  23854.                contains the date and time of the last backup.
  23855.  
  23856. VCBAtrb contains the volume attributes, as follows:
  23857.  
  23858.   Bit    Meaning
  23859.   0–4    Set if inconsistencies were found between the volume
  23860.          information and the file directory when the volume was mounted
  23861.   6      Set if volume is busy (one or more files are open)
  23862.   7      Set if volume is locked by hardware
  23863.   15     Set if volume is locked by software
  23864.  
  23865. VCBVBMSt contains the number of the first block in the volume bit map; on flat volumes,
  23866. it contains the first block of the file directory. VCBNmAlBlks contains the number of
  23867. allocation blocks on the volume, and vcbFreeBks specifies how many of those blocks
  23868. are unused. VCBAlBlSt is used only with flat volumes; it contains the number of the
  23869. first block in the block map.
  23870.  
  23871. VCBDrvNum contains the drive number of the drive on which the volume is mounted;
  23872. vcbDRefNum contains the driver reference number of the driver used to access the
  23873. volume. When a mounted volume is placed off-line, vcbDrvNum is cleared. When a volume
  23874. is ejected, vcbDrvNum is cleared and vcbDRefNum is set to the negative of vcbDrvNum
  23875. (becoming a positive number). VCBFSID identifies the file system handling the volume;
  23876. it’s 0 for volumes handled by the File Manager, and nonzero for volumes handled by
  23877. other file systems.
  23878.  
  23879. When a volume is placed off-line, its buffer and bit map (or block map, in the case
  23880. of flat directory volumes) are released. When a volume is unmounted, its volume
  23881. control block is removed from the volume-control-block queue.
  23882.  
  23883. You can get a pointer to the header of the volume-control-block queue by calling the
  23884. File Manager function GetVCBQHdr.
  23885.  
  23886. æKY DrvQEl
  23887. DrvQElPtr
  23888. æFc Files.h
  23889. æT struct
  23890. æD struct DrvQEl {
  23891.     QElemPtr qLink;
  23892.     short qType;
  23893.     short dQDrive;
  23894.     short dQRefNum;
  23895.     short dQFSID;
  23896.     unsigned short dQDrvSz;
  23897.     unsigned short dQDrvSz2;
  23898. };
  23899.  
  23900. typedef struct DrvQEl DrvQEl;
  23901. typedef DrvQEl *DrvQElPtr;
  23902.  
  23903. æC 
  23904. »The Drive Queue
  23905.  
  23906. •••Refer to Technical Note #36:•••
  23907.  
  23908. Disk drives connected to the Macintosh are opened when the system starts up, and
  23909. information describing each is placed in the drive queue. This is a standard Operating
  23910. System queue, and each entry in it has the following structure:
  23911.  
  23912. TYPE DrvQEl =  RECORD
  23913.                  qLink:     QElemPtr;   {next queue entry}
  23914.                  qType:     INTEGER;    {queue type}
  23915.                  dQDrive:   INTEGER;    {drive number}
  23916.                  dQRefNum:  INTEGER;    {driver reference number}
  23917.                  dQFSID:    INTEGER;    {file-system identifier}
  23918.                  dQDrvSz:   INTEGER;    {number of logical blocks on drive}
  23919.                  dQDrvSz2:  INTEGER;    {additional field to handle large }
  23920.                                         { drive size}
  23921.                END;
  23922.  
  23923. QLink points to the next entry in the queue. If qType is 0, this means the number of
  23924. logical blocks on the drive is contained in the dQDrvSz field alone. If qType is 1,
  23925. both dQDrvSz and dQDrvSz2 are used to store the number of blocks; dqDrvSz2 contains
  23926. the high-order word of this number and dQDrvSz contains the low-order word.
  23927.  
  23928. DQDrive contains the drive number of the drive on which the volume is mounted; dQRefNum
  23929. contains the driver reference number of the driver controlling the device on which
  23930. the volume is mounted. DQFSID identifies the file system handling the volume in the
  23931. drive; it’s 0 for volumes handled by the File Manager, and nonzero for volumes handled
  23932. by other file systems.
  23933.  
  23934. Four bytes of flags precede each drive queue entry; they’re accessible only from
  23935. assembly language.
  23936.  
  23937. Assembly-language note:  These bytes contain the following:
  23938.  
  23939.                            Byte    Contents
  23940.                            0       Bit 7=1 if volume is locked
  23941.                            1       0 if no disk in drive; 1 or 2 if disk
  23942.                                    in drive; 8 if nonejectable disk in drive;
  23943.                                    $FC-$FF if disk was ejected within last 1.5
  23944.                                    seconds; $48 if disk in drive is
  23945.                                    nonejectable but driver wants a call
  23946.                            2       Used internally during system startup
  23947.                            3       Bit 7=0 if disk is single-sided
  23948.  
  23949. You can get a pointer to the header of the drive queue by calling the File Manager
  23950. function GetDrvQHdr.
  23951.  
  23952. æKY NumVersion
  23953. æFc Files.h
  23954. æT struct
  23955. æD struct NumVersion {
  23956.     unsigned char majorRev; /*1st part of version number in BCD*/
  23957.     unsigned int minorRev : 4; /*2nd part is 1 nibble in BCD*/
  23958.     unsigned int bugFixRev : 4; /*3rd part is 1 nibble in BCD*/
  23959.     unsigned char stage; /*stage code: dev, alpha, beta, final*/
  23960.     unsigned char nonRelRev; /*revision level of non-released version*/
  23961. };
  23962.  
  23963. typedef struct NumVersion NumVersion;
  23964. /* Numeric version part of 'vers' resource */
  23965. æC 
  23966.  
  23967. æKY VersRec
  23968. VersRecPtr
  23969. VersRecHndl
  23970. æFc Files.h
  23971. æT struct
  23972. æD struct VersRec {
  23973.     NumVersion numericVersion; /*encoded version number*/
  23974.     short countryCode; /*country code from intl utilities*/
  23975.     Str255 shortVersion; /*version number string - worst case*/
  23976.     Str255 reserved; /*longMessage string packed after shortVersion*/
  23977. };
  23978.  
  23979. typedef struct VersRec VersRec;
  23980. typedef VersRec *VersRecPtr, **VersRecHndl;
  23981.  
  23982. /* 'vers' resource format */
  23983. æC 
  23984.  
  23985. æKY PBHGetVolParms
  23986. æFc Files.h
  23987. æT Function
  23988. æD pascal OSErr PBHGetVolParms(HParmBlkPtr paramBlock,Boolean async); 
  23989. æDT OSErr myVariable = PBHGetVolParms((HParmBlkPtr) paramBlock,(Boolean) async);
  23990. æRI V-392, VI
  23991. æC 
  23992. Trap macro    _GetVolParms
  23993.  
  23994. Parameter block
  23995.   Æ   12  ioCompletion  long  pointer to completion routine
  23996.   ¨   16  ioResult      word  error result code
  23997.   Æ   18  ioFileName    long  volume name specifier
  23998.   Æ   22  ioVRefNum     word  volume refNum
  23999.   ¨   32  ioBuffer      long  pointer to attributes buffer
  24000.   Æ   36  ioReqCount    long  size of buffer area
  24001.   ¨   40  ioActCount    long  length of volume parms data
  24002.  
  24003. <See the description in Volume V. We have a new version of the attributes buffer
  24004. and new values for vMAttrib:>
  24005.  
  24006. Attributes buffer
  24007.   0  vMVersion        word    version number (02 for this version)
  24008.   2  vMAttrib         long    attributes (detailed below)
  24009.   6  vMLocalHand      long    handle to private data for shared volumes
  24010.   10  vMServerAdr     long    AppleTalk server address (0 if not supported)
  24011.   14  vMVolumeGrade   long    Approximate speed rating of volume
  24012.   18  vMAltPrivModel  word    Alternative privilege model supported
  24013.                               (two values currently defined:
  24014.                                0 for an HFS volume;
  24015.                                1 for an A/UX volume)
  24016.  
  24017. Bit positions in vMAttrib
  24018.   31  bLimitFCBs   Limit the number of FCBs used during copying
  24019.                    to 8 instead of 16.
  24020.  
  24021.   30  bLocalWList  Use the returned shared volume handle for the
  24022.                    Finder’s local window list.
  24023.  
  24024.   29  bNoMiniFndr  Disable Mini Finder menu item.
  24025.  
  24026.   28  bNoVNEdit  Lock volume name against editing.
  24027.  
  24028.   27  bNoLclSync  Do not let Finder change the modification date.
  24029.  
  24030.   26  bTrshOffLine  Zoom volume when it goes off line 
  24031.                     to the Trash and when it’s unmounted.
  24032.  
  24033.   25  bNoSwitchTo  Do not switch-launch to any application on the
  24034.                    volume.
  24035.  
  24036.   24-21  Reserved. Server volumes return these bits set.
  24037.                    All other volumes return these bits cleared.
  24038.  
  24039.   20  bNoDeskItems  Do not place objects on the Finder desktop.
  24040.  
  24041.   19  bNoBootBlks  Not a startup volume.
  24042.                    Startup menu item disabled.
  24043.                    Bootblocks not copied.
  24044.  
  24045.   18  bAccessCntl  Volume supports AppleTalk AFP access 
  24046.                    control interfaces. The functions GetLoginInfo, 
  24047.                    GetDirAccess, SetDirAccess, MapID, and 
  24048.                    MapName are supported. Special folder icons are 
  24049.                    used. Access Privileges menu item is enabled
  24050.                    for disk and folder items. The privileges field of 
  24051.                    GetCatInfo calls are assumed to be valid.
  24052.  
  24053.   17  bNoSysDir  Volume doesn’t support a system directory.
  24054.  
  24055.       Do not switch launch to this volume.
  24056.  
  24057.   16  bExtFSVol  Volume is an external file system volume. 
  24058.       Disk initialization package is not called. Erase 
  24059.       Disk menu item is disabled.
  24060.  
  24061.   15  bHasOpenDeny  Volume supports _OpenDeny and 
  24062.                     _OpenRFDeny. For copy operations, source files
  24063.                     are opened with enable read/deny write and 
  24064.                     destination files are opened enable write/deny 
  24065.                     read and write.
  24066.  
  24067.   14  bHasCopyFile  Volume supports _CopyFile. _CopyFile is 
  24068.                     used in copy and duplicate operations if both 
  24069.                     source and destination volumes have same server
  24070.                     address.
  24071.  
  24072.   13  bHasMoveRename  Volume supports _MoveRename.
  24073.  
  24074.   12  bHasNewDesk  Volume supports all of the new desktop 
  24075.                    functions (described in Volume V).
  24076.  
  24077.   11  bHasShortName  Volume supports a name that fits the requirements
  24078.                      of another file system.
  24079.  
  24080.   10  bHasFolderLock  Folder is locked.
  24081.  
  24082.    9  bHasPersonalAccessPrivileges  Macintosh File Share is running.
  24083.  
  24084.    8  bHasUserGroupList  Volume supports the Users and Groups file and
  24085.                          thus the AFP privilege functions.
  24086.  
  24087.    7  bHasCatSearch  Volume supports PBCatSearch.
  24088.  
  24089.    6  bHasFileIDs  Volume supports fileID functions
  24090.  
  24091.    5  For internal use only
  24092.  
  24093.   4-0 Reserved. All volumes return these bits clear.
  24094.  
  24095. æKY PBHGetLogInInfo
  24096. æFc Files.h
  24097. æT Function
  24098. æD pascal OSErr PBHGetLogInInfo(HParmBlkPtr paramBlock,Boolean async); 
  24099. æDT OSErr myVariable = PBHGetLogInInfo((HParmBlkPtr) paramBlock,(Boolean) async);
  24100. æRI V-393
  24101. æC 
  24102. Trap macro    _GetLogInInfo
  24103.  
  24104. Parameter block
  24105.   -->    12    ioCompletion  long    optional completion routine ptr
  24106.   <--    16    ioResult      word    error result code
  24107.   -->    22    ioVRefNum     word    volume refNum
  24108.   <--    26    ioObjType     word    log in method
  24109.   <--    28    ioObjNamePtr  long    ptr to log in name buffer
  24110.  
  24111. PBHGetLogInInfo returns the method used for log-in and the user name specified at
  24112. log-in time for the volume.  The log-in user name is returned as a Pascal string in
  24113. ioObjNamePtr.  The maximum size of the user name is 31 characters.  The log-in method
  24114. type is returned in ioObjType.
  24115.  
  24116. æKY PBHGetDirAccess
  24117. æFc Files.h
  24118. æT Function
  24119. æD pascal OSErr PBHGetDirAccess(HParmBlkPtr paramBlock,Boolean async); 
  24120. æDT OSErr myVariable = PBHGetDirAccess((HParmBlkPtr) paramBlock,(Boolean) async);
  24121. æRI V-394
  24122. æC 
  24123. Trap macro    _GetDirAccess
  24124.  
  24125. Parameter block
  24126.   -->    12    ioCompletion  long    optional completion routine ptr
  24127.   <--    16    ioResult      word    error result code
  24128.   -->    18    ioFileName    long    directory name
  24129.   -->    22    ioVRefNum     word    volume refNum
  24130.   <--    36    ioACOwnerID   long    owner ID
  24131.   <--    40    ioACGroupID   long    group ID
  24132.   <--    44    ioACAccess    long    access rights
  24133.   -->    48    ioDirID       long    directory ID
  24134.  
  24135. PBHGetDirAccess returns access control information for the folder pointed to by the
  24136. ioDirID/ioFIleName pair.  ioACOwnerID will return the ID for the folder’s owner. 
  24137. ioACGroupID will return the ID for the folder’s primary group.  The access rights are
  24138. returned in ioACAccess.
  24139.  
  24140. A fnfErr is returned if the pathname does not point to a valid directory.  An AccessDenied
  24141. error is returned if the user does not have the correct access rights to examine this
  24142. directory.
  24143.  
  24144. æKY PBHSetDirAccess
  24145. æFc Files.h
  24146. æT Function
  24147. æD pascal OSErr PBHSetDirAccess(HParmBlkPtr paramBlock,Boolean async); 
  24148. æDT OSErr myVariable = PBHSetDirAccess((HParmBlkPtr) paramBlock,(Boolean) async);
  24149. æRI V-394
  24150. æC 
  24151. Trap macro    _SetDirAccess
  24152.  
  24153. Parameter block
  24154.   -->    12    ioCompletion  long    optional completion routine ptr
  24155.   <--    16    ioResult      word    error result code
  24156.   -->    18    ioFileName    long    pathname identifier
  24157.   -->    22    ioVRefNum     word    volume refNum
  24158.   -->    36    ioACOwnerID   long    owner ID
  24159.   -->    40    ioACGroupID   long    group ID
  24160.   -->    44    ioACAccess    long    access rights
  24161.   -->    48    ioDirID       long    directory ID
  24162.  
  24163. PBHSetDirAccess allows you to change the access rights to a folder pointed to by the
  24164. ioFileName/ioDirID pair.  IOACOwnerID contains the new owner ID.  IOACGroupID contains
  24165. the group ID.  IOACAccess contains the folder’s access rights.  You cannot set the
  24166. owner bit or the user’s rights of the directory.  To change the owner or group, you
  24167. should set the ioACOwnerID or ioACGroupID field with the appropriate ID of the new
  24168. owner/group.  You must be the owner of the directory to change the owner or group
  24169. ID.
  24170.  
  24171. A fnfErr is returned if the pathname does not point to a valid directory.  An AccessDenied
  24172. error is returned if you do not have the correct access rights to modify the parameters
  24173. for this directory.  A paramErr is returned if you try to set the owner bit or user’s
  24174. rights bits.
  24175.  
  24176. æKY PBHMapID
  24177. æFc Files.h
  24178. æT Function
  24179. æD pascal OSErr PBHMapID(HParmBlkPtr paramBlock,Boolean async); 
  24180. æDT OSErr myVariable = PBHMapID((HParmBlkPtr) paramBlock,(Boolean) async);
  24181. æRI V-395
  24182. æC 
  24183. Trap macro    _MapID
  24184.  
  24185. Parameter block
  24186.   -->    12    ioCompletion  long    optional completion routine ptr
  24187.   <--    16    ioResult      word    error result code
  24188.   -->    18    ioFileName    long    pathname identifier
  24189.   -->    22    ioVRefNum     word    volume refNum
  24190.   -->    26    ioObjType     word    function code
  24191.   <--    28    ioObjNamePtr  long    ptr to retrnd creator/group name
  24192.   -->    32    ioObjID       long    creator/group ID
  24193.  
  24194. PBHMapID returns the name of a user or group given its unique ID.  IOObjID contains
  24195. the ID to be mapped.  The value zero for ioObjID is special cased and will always
  24196. return a NIL name.  AppleShare uses this to signify <Any User>.  IOObjType is the
  24197. mapping function code; it’s 1 if you’re mapping an owner ID to owner name or 2 if
  24198. you’re mapping a group ID to a group name.  The name is returned as a Pascal string
  24199. in ioObjNamePtr.  The maximum size of the name is 31 characters.
  24200.  
  24201. A fnfErr is returned if an unrecognizable owner or group ID is passed.
  24202.  
  24203. æKY PBHMapName
  24204. æFc Files.h
  24205. æT Function
  24206. æD pascal OSErr PBHMapName(HParmBlkPtr paramBlock,Boolean async); 
  24207. æDT OSErr myVariable = PBHMapName((HParmBlkPtr) paramBlock,(Boolean) async);
  24208. æRI V-395
  24209. æC 
  24210. Trap macro    _MapName
  24211.  
  24212. Parameter block
  24213.   -->    12    ioCompletion  long    optional completion routine ptr
  24214.   <--    16    ioResult      word    error result code
  24215.   -->    18    ioFileName    long    volume identifier (may be NIL)
  24216.   -->    22    ioVRefNum     word    volume refNum
  24217.   -->    28    ioObjNamePtr  long    owner or group name
  24218.   -->    26    ioObjType     word    function code
  24219.   <--    32    ioObjID       long    creator/group ID
  24220.  
  24221. PBHMapName returns the unique user ID or group ID given its name.  The name is passed
  24222. as a string in ioObjNamePtr.  If a NIL name is passed, the ID returned will always be
  24223. zero.  The maximum size of the name is 31 characters.  IOObjType is the mapping
  24224. function code; it’s 3 if you’re mapping an owner name to owner ID or 4 if you’re
  24225. mapping a group name to a group ID.  IOObjID will contain the mapped ID.
  24226.  
  24227. A fnfErr is returned if an unrecognizable owner or group name is passed.
  24228.  
  24229. æKY PBHCopyFile
  24230. æFc Files.h
  24231. æT Function
  24232. æD pascal OSErr PBHCopyFile(HParmBlkPtr paramBlock,Boolean async); 
  24233. æDT OSErr myVariable = PBHCopyFile((HParmBlkPtr) paramBlock,(Boolean) async);
  24234. æRI V-396
  24235. æC 
  24236. Trap macro    _CopyFile
  24237.  
  24238. Parameter block
  24239.   -->    12    ioCompletion  long    optional completion routine ptr
  24240.   <--    16    ioResult      word    error result code
  24241.   -->    18    ioFileName    long    ptr to source pathname
  24242.   -->    22    ioVRefNum     word    source vol identifier
  24243.   -->    24    ioDstVRefNum  word    destination vol identifier
  24244.   -->    28    ioNewName     long    ptr to destination pathname
  24245.   -->    32    ioCopyName    long    ptr to optional name (may be NIL)
  24246.   -->    36    ioNewDirID    long    destination directory ID
  24247.   -->    48    ioDirID       long    source directory ID
  24248.  
  24249. PBHCopyFile duplicates a file on the volume and optionally renames it.  It is an
  24250. optional call for AppleShare file servers.  You should examine the returned flag
  24251. information in the PBHGetVolParms call to see if this volume supports CopyFile.
  24252.  
  24253. For AppleShare file servers, the source and destination pathnames must indicate the
  24254. same file server; however, it may point to a different volume for that file server. 
  24255. A useful way to tell if two file server volumes are on the same file server is to
  24256. make the GetVolParms call and compare the server addresses returned.  The server will
  24257. open source files with read/deny write enabled and destination files with write/deny
  24258. read and write enabled.
  24259.  
  24260. IOVRefNum contains a source volume identifier.  The source pathname is determined by
  24261. the ioFileName/ioDirID pair.  IODstVRefNum contains a destination volume identifier. 
  24262. AppleShare 1.0 required that it be an actual volume reference number; however, on
  24263. future versions it can be a WDRefNum.  The destination pathname is determined by the
  24264. ioNewName/ioNewDirID pair.  IOCopyName may contain an optional string used in renaming
  24265. the file.  If it is non-NIL then the file copy will be renamed to the specified name
  24266. in ioCopyName.
  24267.  
  24268. A fnfErr is returned if the source pathname does not point to an existing file or the
  24269. destination pathname does not point to an existing directory.  An AccessDenied error
  24270. is returned if the user does not have the right to read the source or write to the
  24271. destination.  A dupFnErr is returned if the destination already exists.  A DenyConflict
  24272. error is returned if either the source or destination file could not be opened under
  24273. the access modes described above.
  24274.  
  24275. æKY PBHMoveRename
  24276. æFc Files.h
  24277. æT Function
  24278. æD pascal OSErr PBHMoveRename(HParmBlkPtr paramBlock,Boolean async); 
  24279. æDT OSErr myVariable = PBHMoveRename((HParmBlkPtr) paramBlock,(Boolean) async);
  24280. æRI V-397
  24281. æC 
  24282. Trap macro    _MoveRename
  24283.  
  24284. Parameter block
  24285.   -->    12    ioCompletion  long    optional completion routine ptr
  24286.   <--    16    ioResult      word    error result code
  24287.   -->    18    ioFileName    long    ptr to source pathname
  24288.   -->    22    ioVRefNum     word    source vol identifier
  24289.   -->    28    ioNewName     long    ptr to destination pathname
  24290.   -->    32    ioBuffer      long    ptr to optional name (may be NIL)
  24291.   -->    36    ioNewDirID    long    destination directory ID
  24292.   -->    48    ioDirID       long    source directory ID
  24293.  
  24294. PBHMoveRename allows you to move (not copy) an item and optionally to rename it.  The
  24295. source and destination pathnames must point to the same file server volume.
  24296.  
  24297. IOVRefNum contains a source volume identifier.  The source pathname is specified by
  24298. the ioFileName/ioDirID pair.  The destination pathname is specified by the ioNewName/ioNewDirID
  24299. pair.  IOBuffer may contain an optional string used in renaming the item.  If it is
  24300. non-NIL then the moved object will be renamed to the specified name in ioBuffer.
  24301.  
  24302. A fnfErr is returned if the source pathname does not point to an existing object.  An
  24303. AccessDenied error is returned if the user does not have the right to move the object.
  24304.  A dupFnErr is returned if the destination already exists.  A badMovErr is returned
  24305. if an attempt is made to move a directory into one of its descendent directories.
  24306.  
  24307. æKY PBHOpenDeny
  24308. æFc Files.h
  24309. æT Function
  24310. æD pascal OSErr PBHOpenDeny(HParmBlkPtr paramBlock,Boolean async); 
  24311. æDT OSErr myVariable = PBHOpenDeny((HParmBlkPtr) paramBlock,(Boolean) async);
  24312. æRI V-398
  24313. æC 
  24314. Trap macro    _OpenDeny
  24315.  
  24316. Parameter block
  24317.   -->    12    ioCompletion  long    optional completion routine ptr
  24318.   <--    16    ioResult      word    error result code
  24319.   -->    18    ioFileName    long    ptr to pathname
  24320.   -->    22    ioVRefNum     word    vol identifier
  24321.   <--    24    ioRefNum      word    file refNum
  24322.   -->    26    ioDenyModes   word    access rights data
  24323.   -->    48    ioDirID       long    directory ID
  24324.  
  24325. PBHOpenDeny opens a file’s data fork under specific access rights.  It creates an
  24326. access path to the file having the name pointed to by ioFileName/ioDirID.  The path
  24327. reference number is returned in ioRefNum.
  24328.  
  24329. IODenyModes contains a word of access rights information.  The format for these
  24330. access rights is:
  24331.  
  24332.     bits    15–6    Reserved—should be cleared.
  24333.             5       If set, other writers are denied access.
  24334.             4       If set, other readers are denied access.
  24335.             3–2     Reserved—should be cleared.
  24336.             1       If set, write permission requested.
  24337.             0       If set, read permission requested.
  24338.  
  24339. A fnfErr is returned if the input specification does not point to an existing file. 
  24340. A permErr is returned if the file is already open and you cannot open it under the
  24341. deny modes that you have specified.  An opWrErr is returned if you have asked for
  24342. write permission and the file is already opened by you for write.  The already opened
  24343. path reference number is returned in ioRefNum.  An AccessDenied error is returned if
  24344. you do not have the right to access the file.
  24345.  
  24346. æKY PBHOpenRFDeny
  24347. æFc Files.h
  24348. æT Function
  24349. æD pascal OSErr PBHOpenRFDeny(HParmBlkPtr paramBlock,Boolean async); 
  24350. æDT OSErr myVariable = PBHOpenRFDeny((HParmBlkPtr) paramBlock,(Boolean) async);
  24351. æRI V-398
  24352. æC 
  24353. Trap macro    _OpenRFDeny
  24354.  
  24355. Parameter block
  24356.   -->    12    ioCompletion  long    optional completion routine ptr
  24357.   <--    16    ioResult      word    error result code
  24358.   -->    18    ioFileName    long    ptr to pathname
  24359.   -->    22    ioVRefNum     word    vol identifier
  24360.   <--    24    ioRefNum      word    file refNum
  24361.   -->    26    ioDenyModes   word    access rights data
  24362.   -->    48    ioDirID       long    directory ID
  24363.  
  24364. PBHOpenRFDeny opens a file’s resource fork under specific access rights.
  24365. It creates an access path to the file having the name pointed to by
  24366. ioFileName/ioDirID.  The path reference number is returned in ioRefNum.  The format
  24367. of the access rights data contained in ioDenyModes is described under the OpenDeny
  24368. call.
  24369.  
  24370. A fnfErr is returned if the input specification does not point to an existing file. 
  24371. A permErr is returned if the file is already open and you cannot open it under the
  24372. deny modes that you have specified.  An opWrErr is returned if you have asked for
  24373. write permission and the file is already opened by you for write.  The already-opened
  24374. path reference number is returned in ioRefNum.  An AccessDenied error is returned if
  24375. you do not have the right to access the file.
  24376.  
  24377. æKY PBOpen
  24378. æFc Files.h
  24379. æT Function
  24380. æD pascal OSErr PBOpen(ParmBlkPtr paramBlock,Boolean async); 
  24381. æDT OSErr myVariable = PBOpen((ParmBlkPtr) paramBlock,(Boolean) async);
  24382. æRI II-108
  24383. æC 
  24384. Trap macro    _Open
  24385.  
  24386. Parameter block
  24387.   -->    12    ioCompletion  pointer
  24388.   <--    16    ioResult      word
  24389.   -->    18    ioNamePtr     pointer
  24390.   -->    22    ioVRefNum     word
  24391.   <--    24    ioRefNum      word
  24392.   -->    26    ioVersNum     byte
  24393.   -->    27    ioPermssn     byte
  24394.   -->    28    ioMisc        pointer
  24395.  
  24396. PBOpen creates an access path to the file having the name pointed to by ioNamePtr
  24397. (and on flat volumes, the version number ioVersNum) on the volume specified by ioVRefNum.
  24398. A path reference number is returned in ioRefNum.
  24399.  
  24400. IOMisc either points to a portion of memory (522 bytes) to be used as the access
  24401. path’s buffer, or is NIL if you want the volume buffer to be used instead.
  24402.  
  24403. Warning:  All access paths to a single file that’s opened multiple times
  24404.           should share the same buffer so that they will read and write
  24405.           the same data.
  24406.  
  24407. IOPermssn specifies the path’s read/write permission. A path can be opened for writing
  24408. even if it accesses a file on a locked volume, and an error won’t be returned until a
  24409. PBWrite, PBSetEOF, or PBAllocate call is made.
  24410.  
  24411. If you attempt to open a locked file for writing, PBOpen will return permErr as its
  24412. function result. If you request exclusive read/write permission but another access
  24413. path already has write permission (whether write only, exclusive
  24414. read/write, or shared read/write), PBOpen will return the reference number of the
  24415. existing access path in ioRefNum and opWrErr as its function result. Similarly, if
  24416. you request shared read/write permission but another access path already has exclusive
  24417. read/write permission, PBOpen will return the reference number of the access path in
  24418. ioRefNum and opWrErr as its function result.
  24419.  
  24420. Result codes    noErr     No error
  24421.                 bdNamErr  Bad file name
  24422.                 extFSErr  External file system
  24423.                 fnfErr    File not found
  24424.                 ioErr     I/O error
  24425.                 nsvErr    No such volume
  24426.                 opWrErr   File already open for writing
  24427.                 permErr   Attempt to open locked file for writing
  24428.                 tmfoErr   Too many files open
  24429.  
  24430. æKY PBClose
  24431. æFc Files.h
  24432. æT Function
  24433. æD pascal OSErr PBClose(ParmBlkPtr paramBlock,Boolean async); 
  24434. æDT OSErr myVariable = PBClose((ParmBlkPtr) paramBlock,(Boolean) async);
  24435. æRI II-114
  24436. æC 
  24437. Trap macro     _Close
  24438.  
  24439. Parameter block
  24440.   -->    12    ioCompletion  pointer
  24441.   <--    16    ioResult      word
  24442.   -->    24    ioRefNum      word
  24443.  
  24444. PBClose writes the contents of the access path buffer specified by ioRefNum to the
  24445. volume and removes the access path.
  24446.  
  24447. Warning:  Some information stored on the volume won’t be correct
  24448.           until PBFlushVol is called.
  24449.  
  24450. Result codes    noErr     No error
  24451.                 extFSErr  External file system
  24452.                 fnfErr    File not found
  24453.                 fnOpnErr  File not open
  24454.                 ioErr     I/O error
  24455.                 nsvErr    No such volume
  24456.                 rfNumErr  Bad reference number
  24457.  
  24458. æKY PBRead
  24459. æFc Files.h
  24460. æT Function
  24461. æD pascal OSErr PBRead(ParmBlkPtr paramBlock,Boolean async); 
  24462. æDT OSErr myVariable = PBRead((ParmBlkPtr) paramBlock,(Boolean) async);
  24463. æRT 187
  24464. æRI II-110
  24465. æC  
  24466. Trap macro    _Read
  24467.  
  24468. Parameter block
  24469.   -->    12    ioCompletion  pointer
  24470.   <--    16    ioResult      word
  24471.   -->    24    ioRefNum      word
  24472.   -->    32    ioBuffer      pointer
  24473.   -->    36    ioReqCount    long word
  24474.   <--    40    ioActCount    long word
  24475.   -->    44    ioPosMode     word
  24476.   <->    46    ioPosOffset   long word
  24477.  
  24478. PBRead attempts to read ioReqCount bytes from the open file whose access path is
  24479. specified by ioRefNum, and transfer them to the data buffer pointed to by ioBuffer.
  24480. The position of the mark is specified by ioPosMode and ioPosOffset. If you try to
  24481. read past the logical end-of-file, PBRead moves the mark to the end-of-file and
  24482. returns eofErr as its function result. After the read is completed, the mark is
  24483. returned in ioPosOffset and the number of bytes actually read is returned in ioActCount.
  24484.  
  24485. Result codes    noErr     No error
  24486.                 eofErr    End-of-file
  24487.                 extFSErr  External file system
  24488.                 fnOpnErr  File not open
  24489.                 ioErr     I/O error
  24490.                 paramErr  Negative ioReqCount
  24491.                 rfNumErr  Bad reference number
  24492.  
  24493. æKY PBWrite
  24494. æFc Files.h
  24495. æT Function
  24496. æD pascal OSErr PBWrite(ParmBlkPtr paramBlock,Boolean async); 
  24497. æDT OSErr myVariable = PBWrite((ParmBlkPtr) paramBlock,(Boolean) async);
  24498. æRT 187
  24499. æRI II-110
  24500. æC 
  24501.  
  24502. •••Refer to Technical Note #187:•••
  24503.  
  24504. Trap macro    _Write
  24505.  
  24506. Parameter block
  24507.   -->    12    ioCompletion  pointer
  24508.   <--    16    ioResult      word
  24509.   -->    24    ioRefNum      word
  24510.   -->    32    ioBuffer      pointer
  24511.   -->    36    ioReqCount    long word
  24512.   <--    40    ioActCount    long word
  24513.   -->    44    ioPosMode     word
  24514.   <->    46    ioPosOffset   long word
  24515.  
  24516. PBWrite takes ioReqCount bytes from the buffer pointed to by ioBuffer and attempts to
  24517. write them to the open file whose access path is specified by ioRefNum. The position
  24518. of the mark is specified by ioPosMode and ioPosOffset. After the write is completed,
  24519. the mark is returned in ioPosOffset and the number of bytes actually written is
  24520. returned in ioActCount.
  24521.  
  24522. Result codes    noErr      No error
  24523.                 dskFulErr  Disk full
  24524.                 fLckdErr   File locked
  24525.                 fnOpnErr   File not open
  24526.                 ioErr      I/O error
  24527.                 paramErr   Negative ioReqCount
  24528.                 posErr     Attempt to position before start of file
  24529.                 rfNumErr   Bad reference number
  24530.                 vLckdErr   Software volume lock
  24531.                 wPrErr     Hardware volume lock
  24532.                 wrPermErr  Read/write permission doesn’t allow writing
  24533.  
  24534. æKY PBGetVInfo
  24535. æFc Files.h
  24536. æT Function
  24537. æD pascal OSErr PBGetVInfo(ParmBlkPtr paramBlock,Boolean async); 
  24538. æDT OSErr myVariable = PBGetVInfo((ParmBlkPtr) paramBlock,(Boolean) async);
  24539. æRT 24, 44, 157
  24540. æRI II-104, IV-129, N24-1, N44-2, N157
  24541. æC 
  24542. Trap macro    _GetVolInfo
  24543.  
  24544. Parameter block
  24545.   -->    12    ioCompletion  pointer
  24546.   <--    16    ioResult      word
  24547.   <->    18    ioNamePtr     pointer
  24548.   <->    22    ioVRefNum     word
  24549.   -->    28    ioVolIndex    word
  24550.   <--    30    ioVCrDate     long word
  24551.   <--    34    ioVLsBkUp     long word
  24552.   <--    38    ioVAtrb       word
  24553.   <--    40    ioVNmFls      word
  24554.   <--    42    ioVDirSt      word
  24555.   <--    44    ioVBlLn       word
  24556.   <--    46    ioVNmAlBlks   word
  24557.   <--    48    ioVAlBlkSiz   long word
  24558.   <--    52    ioVClpSiz     long word
  24559.   <--    56    ioAlBlSt      word
  24560.   <--    58    ioVNxtFNum    long word
  24561.   <--    62    ioVFrBlk      word
  24562.  
  24563. PBGetVInfo returns information about the specified volume. If ioVolIndex is positive,
  24564. the File Manager attempts to use it to find the volume; for instance, if ioVolIndex
  24565. is 2, the File Manager will attempt to access the second mounted volume. If ioVolIndex
  24566. is negative, the File Manager uses ioNamePtr and ioVRefNum in the standard way (described
  24567. in the section “Specifying Volumes, Directories, and Files”) to determine which
  24568. volume. If ioVolIndex is 0, the File Manager attempts to access the volume by using
  24569. ioVRefNum only. The volume reference number is returned in ioVRefNum, and a pointer
  24570. to the volume name is returned in ioNamePtr (unless ioNamePtr is NIL).
  24571.  
  24572. If a working directory reference number is passed in ioVRefNum (or if the default
  24573. directory is a subdirectory), the number of files and directories in the specified
  24574. directory (the directory’s valence) will be returned in ioVNmFls. Also, the volume
  24575. reference number won’t be returned; ioVRefNum will still contain the working directory
  24576. reference number.
  24577.  
  24578. Warning:  IOVNmAlBlks and ioVFrBlks, which are actually unsigned integers,
  24579.           are clipped to 31744 ($7C00) regardless of the size of the volume.
  24580.  
  24581. Result codes    noErr       No error
  24582.                 nsvErr      No such volume
  24583.                 paramErr    No default volume
  24584.  
  24585. æKY PBGetVol
  24586. æFc Files.h
  24587. æT Function
  24588. æD pascal OSErr PBGetVol(ParmBlkPtr paramBlock,Boolean async); 
  24589. æDT OSErr myVariable = PBGetVol((ParmBlkPtr) paramBlock,(Boolean) async);
  24590. æRI II-104, IV-131
  24591. æC 
  24592. Trap macro    _GetVol
  24593.  
  24594. Parameter block
  24595.   -->    12    ioCompletion  pointer
  24596.   <--    16    ioResult      word
  24597.   <--    18    ioNamePtr     pointer
  24598.   <--    22    ioVRefNum     word
  24599.  
  24600. PBGetVol returns a pointer to the name of the default volume in ioNamePtr
  24601. (unless ioNamePtr is NIL) and its volume reference number in ioVRefNum. If a default
  24602. directory was set with a previous PBSetVol call, a pointer to its name will be returned
  24603. in ioNamePtr and its working directory reference number in ioVRefNum.
  24604.  
  24605. Result codes    noErr     No error
  24606.                 nsvErr    No default volume
  24607.  
  24608. æKY PBSetVol
  24609. æFc Files.h
  24610. æT Function
  24611. æD pascal OSErr PBSetVol(ParmBlkPtr paramBlock,Boolean async); 
  24612. æDT OSErr myVariable = PBSetVol((ParmBlkPtr) paramBlock,(Boolean) async);
  24613. æRI II-105,  IV-132
  24614. æC 
  24615. Trap macro    _SetVol
  24616.  
  24617. Parameter block
  24618.   -->    12    ioCompletion  pointer
  24619.   <--    16    ioResult      word
  24620.   -->    18    ioNamePtr     pointer
  24621.   -->    22    ioVRefNum     word
  24622.  
  24623. PBSetVol sets the default volume to the mounted volume specified by ioNamePtr or
  24624. ioVRefNum. On hierarchical volumes, PBSetVol also sets the root directory as the
  24625. default directory.
  24626.  
  24627. Result codes    noErr     No error
  24628.                 bdNamErr  Bad volume name
  24629.                 nsvErr    No such volume
  24630.                 paramErr  No default volume
  24631.  
  24632. æKY PBFlushVol
  24633. æFc Files.h
  24634. æT Function
  24635. æD pascal OSErr PBFlushVol(ParmBlkPtr paramBlock,Boolean async); 
  24636. æDT OSErr myVariable = PBFlushVol((ParmBlkPtr) paramBlock,(Boolean) async);
  24637. æMM
  24638. æRI II-105, IV-133
  24639. æC 
  24640. Trap macro    _FlushVol
  24641.  
  24642. Parameter block
  24643.   -->    12    ioCompletion  pointer
  24644.   <--    16    ioResult      word
  24645.   -->    18    ioNamePtr     pointer
  24646.   -->    22    ioVRefNum     word
  24647.  
  24648. On the volume specified by ioNamePtr or ioVRefNum, PBFlushVol writes descriptive
  24649. information about the volume, the contents of the associated volume buffer, and all
  24650. access path buffers for the volume (if they’ve changed since the last time PBFlushVol
  24651. was called).
  24652.  
  24653. Note:  The date and time of the last modification to the volume are set
  24654.        when the modification is made, not when the volume is flushed.
  24655.  
  24656. Result codes    noErr     No error
  24657.                 bdNamErr  Bad volume name
  24658.                 extFSErr  External file system
  24659.                 ioErr     I/O error
  24660.                 nsDrvErr  No such drive
  24661.                 nsvErr    No such volume
  24662.                 paramErr  No default volume
  24663.  
  24664. æKY PBCreate
  24665. æFc Files.h
  24666. æT Function
  24667. æD pascal OSErr PBCreate(ParmBlkPtr paramBlock,Boolean async); 
  24668. æDT OSErr myVariable = PBCreate((ParmBlkPtr) paramBlock,(Boolean) async);
  24669. æRI II-107, IV-145
  24670. æC 
  24671. Trap macro    _Create
  24672.  
  24673. Parameter block
  24674.   -->    12    ioCompletion  pointer
  24675.   <--    16    ioResult      word
  24676.   -->    18    ioNamePtr     pointer
  24677.   -->    22    ioVRefNum     word
  24678.   -->    26    ioFVersNum    byte
  24679.  
  24680. PBCreate creates a new file (both forks) having the name pointed to by ioNamePtr (and
  24681. on flat volumes, the version number ioVersNum) on the volume specified by ioVRefNum.
  24682. The new file is unlocked and empty. The date and time of its creation and last modification
  24683. are set to the current date and time. If the file created isn’t temporary (that is,
  24684. if it will exist after the application terminates), the application should call
  24685. PBSetFInfo (after PBCreate) to fill in the information needed by the Finder.
  24686.  
  24687. Assembly-language note:  If a desk accessory creates a file, it should
  24688.                          always create it in the directory containing the
  24689.                          system folder. The working directory reference
  24690.                          number for this directory is stored in the global
  24691.                          variable BootDrive; you can pass it in ioVRefNum.
  24692.  
  24693. Result codes    noErr      No error
  24694.                 bdNamErr   Bad file name
  24695.                 dupFNErr   Duplicate file name and version
  24696.                 dirFulErr  File directory full
  24697.                 extFSErr   External file system
  24698.                 ioErr      I/O error
  24699.                 nsvErr     No such volume
  24700.                 vLckdErr   Software volume lock
  24701.                 wPrErr     Hardware volume lock
  24702.  
  24703. æKY PBDelete
  24704. æFc Files.h
  24705. æT Function
  24706. æD pascal OSErr PBDelete(ParmBlkPtr paramBlock,Boolean async); 
  24707. æDT OSErr myVariable = PBDelete((ParmBlkPtr) paramBlock,(Boolean) async);
  24708. æRI II-119, IV-147
  24709. æC 
  24710. Trap macro    _Delete
  24711.  
  24712. Parameter block
  24713.   -->    12    ioCompletion  pointer
  24714.   <--    16    ioResult      word
  24715.   -->    18    ioNamePtr     pointer
  24716.   -->    22    ioVRefNum     word
  24717.   -->    26    ioFVersNum    byte
  24718.  
  24719. PBDelete removes the closed file having the name pointed to by ioNamePtr (and on flat
  24720. volumes, the version number ioVersNum) from the volume pointed to by ioVRefNum.
  24721. PBHDelete can be used to delete an empty directory as well.
  24722.  
  24723. Note:  This function will delete both forks of the file.
  24724.  
  24725. Result codes    noErr     No error
  24726.                 bdNamErr  Bad file name
  24727.                 extFSErr  External file system
  24728.                 fBsyErr   File busy, directory not empty, or working
  24729.                           directory control block open
  24730.                 fLckdErr  File locked
  24731.                 fnfErr    File not found
  24732.                 nsvErr    No such volume
  24733.                 ioErr     I/O error
  24734.                 vLckdErr  Software volume lock
  24735.                 wPrErr    Hardware volume lock
  24736.  
  24737. æKY PBOpenRF
  24738. æFc Files.h
  24739. æT Function
  24740. æD pascal OSErr PBOpenRF(ParmBlkPtr paramBlock,Boolean async); 
  24741. æDT OSErr myVariable = PBOpenRF((ParmBlkPtr) paramBlock,(Boolean) async);
  24742. æMM
  24743. æRT 74
  24744. æRI II-109, IV-137 
  24745. æC 
  24746. Trap macro    _OpenRF
  24747.  
  24748. Parameter block
  24749.   -->    12    ioCompletion  pointer
  24750.   <--    16    ioResult      word
  24751.   -->    18    ioNamePtr     pointer
  24752.   -->    22    ioVRefNum     word
  24753.   <--    24    ioRefNum      word
  24754.   -->    26    ioVersNum     byte
  24755.   -->    27    ioPermssn     byte
  24756.   -->    28    ioMisc        pointer
  24757.  
  24758. PBOpenRF is identical to PBOpen, except that it opens the file’s resource fork instead
  24759. of its data fork.
  24760.  
  24761. Note:  Normally you should access a file’s resource fork through the
  24762.        routines of the Resource Manager rather than the File Manager.
  24763.        PBOpenRF doesn’t read the resource map into memory; it’s really
  24764.        only useful for block-level operations such as copying files.
  24765.  
  24766. Result codes    noErr     No error
  24767.                 bdNamErr  Bad file name
  24768.                 extFSErr  External file system
  24769.                 fnfErr    File not found
  24770.                 ioErr     I/O error
  24771.                 nsvErr    No such volume
  24772.                 opWrErr   File already open for writing
  24773.                 permErr   Attempt to open locked file for writing
  24774.                 tmfoErr   Too many files open
  24775.  
  24776. æKY PBRename
  24777. æFc Files.h
  24778. æT Function
  24779. æD pascal OSErr PBRename(ParmBlkPtr paramBlock,Boolean async); 
  24780. æDT OSErr myVariable = PBRename((ParmBlkPtr) paramBlock,(Boolean) async);
  24781. æRI II-118, IV-153
  24782. æC 
  24783. Trap macro    _Rename
  24784.  
  24785. Parameter block
  24786.   -->    12    ioCompletion  pointer
  24787.   <--    16    ioResult      word
  24788.   -->    18    ioNamePtr     pointer
  24789.   -->    22    ioVRefNum     word
  24790.   -->    26    ioVersNum     byte
  24791.   -->    28    ioMisc        pointer
  24792.  
  24793. Given a pointer to a file name in ioNamePtr (and on flat volumes, a version number in
  24794. ioVersNum), PBRename changes the name of the file to the name pointed to by ioMisc.
  24795. (If the name pointed to by ioNamePtr contains one or more colons, so must the name
  24796. pointed to by ioMisc.) Access paths currently in use aren’t affected. Given a pointer
  24797. to a volume name in ioNamePtr or a volume reference number in ioVRefNum, it changes
  24798. the name of the volume to the name pointed to by ioMisc. If a volume to be renamed is
  24799. specified by its volume reference number, ioNamePtr can be NIL.
  24800.  
  24801. Warning:  If a volume to be renamed is specified by its volume name, be
  24802.           sure that it ends with a colon, or Rename will consider it a
  24803.           file name.
  24804.  
  24805. Result codes    noErr      No error
  24806.                 bdNamErr   Bad file name
  24807.                 dirFulErr  File directory full
  24808.                 dupFNErr   Duplicate file name and version
  24809.                 extFSErr   External file system
  24810.                 fLckdErr   File locked
  24811.                 fnfErr     File not found
  24812.                 fsRnErr    Problem during rename
  24813.                 ioErr      I/O error
  24814.                 nsvErr     No such volume
  24815.                 paramErr   No default volume
  24816.                 vLckdErr   Software volume lock
  24817.                 wPrErr     Hardware volume lock
  24818.  
  24819. æKY PBGetFInfo
  24820. æFc Files.h
  24821. æT Function
  24822. æD pascal OSErr PBGetFInfo(ParmBlkPtr paramBlock,Boolean async); 
  24823. æDT OSErr myVariable = PBGetFInfo((ParmBlkPtr) paramBlock,(Boolean) async);
  24824. æRT 24
  24825. æRI II-115, IV-148, N24-1, N68-1
  24826. æC 
  24827. Trap macro    _GetFileInfo
  24828.  
  24829. Parameter block
  24830.   -->    12    ioCompletion  pointer
  24831.   <--    16    ioResult      word
  24832.   <->    18    ioNamePtr     pointer
  24833.   -->    22    ioVRefNum     word
  24834.   <--    24    ioFRefNum     word
  24835.   -->    26    ioFVersNum    byte
  24836.   -->    28    ioFDirIndex   word
  24837.   <--    30    ioFlAttrib    byte
  24838.   <--    31    ioFlVersNum   byte
  24839.   <--    32    ioFlFndrInfo  16 bytes
  24840.   <--    48    ioFlNum       long word
  24841.   <--    52    ioFlStBlk     word
  24842.   <--    54    ioFlLgLen     long word
  24843.   <--    58    ioFlPyLen     long word
  24844.   <--    62    ioFlRStBlk    word
  24845.   <--    64    ioFlRLgLen    long word
  24846.   <--    68    ioFlRPyLen    long word
  24847.   <--    72    ioFlCrDat     long word
  24848.   <--    76    ioFlMdDat     long word
  24849.  
  24850. PBGetFInfo returns information about the specified file. If ioFDirIndex is positive,
  24851. the File Manager returns information about the file whose directory index is ioFDirIndex
  24852. on the volume specified by ioVRefNum. (See the section
  24853. “Data Organization on Volumes” if you’re interested in using this method.)
  24854.  
  24855. Note:  If a working directory reference number is specified in ioVRefNum,
  24856.        the File Manager returns information about the file whose directory
  24857.        index is ioFDirIndex in the specified directory.
  24858.  
  24859. If ioFDirIndex is negative or 0, the File Manager returns information about the file
  24860. having the name pointed to by ioNamePtr (and on flat volumes, the version number
  24861. ioFVersNum) on the volume specified by ioVRefNum. If the file is open, the reference
  24862. number of the first access path found is returned in ioFRefNum, and the name of the
  24863. file is returned in ioNamePtr (unless ioNamePtr is NIL).
  24864.  
  24865. Result codes    noErr     No error
  24866.                 bdNamErr  Bad file name
  24867.                 extFSErr  External file system
  24868.                 fnfErr    File not found
  24869.                 ioErr     I/O error
  24870.                 nsvErr    No such volume
  24871.                 paramErr  No default volume
  24872.  
  24873. æKY PBSetFInfo
  24874. æFc Files.h
  24875. æT Function
  24876. æD pascal OSErr PBSetFInfo(ParmBlkPtr paramBlock,Boolean async); 
  24877. æDT OSErr myVariable = PBSetFInfo((ParmBlkPtr) paramBlock,(Boolean) async);
  24878. æRI II-116, IV-150
  24879. æC 
  24880. Trap macro    _SetFileInfo
  24881.  
  24882. Parameter block
  24883.   -->    12    ioCompletion  pointer
  24884.   <--    16    ioResult      word
  24885.   -->    18    ioNamePtr     pointer
  24886.   -->    22    ioVRefNum     word
  24887.   -->    26    ioFVersNum    byte
  24888.   -->    32    ioFlFndrInfo  16 bytes
  24889.   -->    72    ioFlCrDat     long word
  24890.   -->    76    ioFlMdDat     long word
  24891.  
  24892. PBSetFInfo sets information (including the date and time of creation and modification,
  24893. and information needed by the Finder) about the file having the name pointed to by
  24894. ioNamePtr (and on flat volumes, the version number ioFVersNum) on the volume specified
  24895. by ioVRefNum. You should call PBGetFInfo just before PBSetFInfo, so the current
  24896. information is present in the parameter block.
  24897.  
  24898. Result codes    noErr     No error
  24899.                 bdNamErr  Bad file name
  24900.                 extFSErr  External file system
  24901.                 fLckdErr  File locked
  24902.                 fnfErr    File not found
  24903.                 ioErr     I/O error
  24904.                 nsvErr    No such volume
  24905.                 vLckdErr  Software volume lock
  24906.                 wPrErr    Hardware volume lock
  24907.  
  24908. æKY PBSetFLock
  24909. æFc Files.h
  24910. æT Function
  24911. æD pascal OSErr PBSetFLock(ParmBlkPtr paramBlock,Boolean async); 
  24912. æDT OSErr myVariable = PBSetFLock((ParmBlkPtr) paramBlock,(Boolean) async);
  24913. æRI II-116, IV-151
  24914. æC 
  24915. Trap macro    _SetFilLock
  24916.  
  24917. Parameter block
  24918.   -->    12    ioCompletion  pointer
  24919.   <--    16    ioResult      word
  24920.   -->    18    ioNamePtr     pointer
  24921.   -->    22    ioVRefNum     word
  24922.   -->    26    ioFVersNum    byte
  24923.  
  24924. PBSetFLock locks the file having the name pointed to by ioNamePtr (and on flat volumes,
  24925. the version number ioFVersNum) on the volume specified by ioVRefNum. Access paths
  24926. currently in use aren’t affected.
  24927.  
  24928. Result codes    noErr     No error
  24929.                 extFSErr  External file system
  24930.                 fnfErr    File not found
  24931.                 ioErr     I/O error
  24932.                 nsvErr    No such volume
  24933.                 vLckdErr  Software volume lock
  24934.                 wPrErr    Hardware volume lock
  24935.  
  24936. æKY PBRstFLock
  24937. æFc Files.h
  24938. æT Function
  24939. æD pascal OSErr PBRstFLock(ParmBlkPtr paramBlock,Boolean async); 
  24940. æDT OSErr myVariable = PBRstFLock((ParmBlkPtr) paramBlock,(Boolean) async);
  24941. æRI II-117, IV-152
  24942. æC 
  24943. Trap macro    _RstFilLock
  24944.  
  24945. Parameter block
  24946.   -->    12    ioCompletion  pointer
  24947.   <--    16    ioResult      word
  24948.   -->    18    ioNamePtr     pointer
  24949.   -->    22    ioVRefNum     word
  24950.   -->    26    ioFVersNum    byte
  24951.  
  24952. PBRstFLock unlocks the file having the name pointed to by ioNamePtr (and on flat
  24953. volumes, the version number ioFVersNum) on the volume specified by ioVRefNum. Access
  24954. paths currently in use aren’t affected.
  24955.  
  24956. Result codes    noErr     No error
  24957.                 extFSErr  External file system
  24958.                 fnfErr    File not found
  24959.                 ioErr     I/O error
  24960.                 nsvErr    No such volume
  24961.                 vLckdErr  Software volume lock
  24962.                 wPrErr    Hardware volume lock
  24963.  
  24964. æKY PBSetFVers
  24965. æFc Files.h
  24966. æT Function
  24967. æD pascal OSErr PBSetFVers(ParmBlkPtr paramBlock,Boolean async); 
  24968. æDT OSErr myVariable = PBSetFVers((ParmBlkPtr) paramBlock,(Boolean) async);
  24969. æRI II-117, IV-153
  24970. æC 
  24971. Trap macro    _SetFilType
  24972.  
  24973. Parameter block
  24974.   -->    12    ioCompletion  pointer
  24975.   <--    16    ioResult      word
  24976.   -->    18    ioNamePtr     pointer
  24977.   -->    22    ioVRefNum     word
  24978.   -->    26    ioVersNum     byte
  24979.   -->    28    ioMisc        byte
  24980.  
  24981. PBSetFVers has no effect on hierarchical volumes. On flat volumes, PBSetFVers changes
  24982. the version number of the file having the name pointed to by ioNamePtr and version
  24983. number ioVersNum, on the volume specified by ioVRefNum, to the version number stored
  24984. in the high-order byte of ioMisc. Access paths currently in use aren’t affected.
  24985.  
  24986. Result codes    noErr         No error
  24987.                 bdNamErr      Bad file name
  24988.                 dupFNErr      Duplicate file name and version
  24989.                 extFSErr      External file system
  24990.                 fLckdErr      File locked
  24991.                 fnfErr        File not found
  24992.                 nsvErr        No such volume
  24993.                 ioErr         I/O error
  24994.                 paramErr      No default volume
  24995.                 vLckdErr      Software volume lock
  24996.                 wPrErr        Hardware volume lock
  24997.                 wrgVolTypErr  Attempt to perform hierarchical operation
  24998.                               on a flat volume
  24999.  
  25000. æKY PBAllocate
  25001. æFc Files.h
  25002. æT Function
  25003. æD pascal OSErr PBAllocate(ParmBlkPtr paramBlock,Boolean async); 
  25004. æDT OSErr myVariable = PBAllocate((ParmBlkPtr) paramBlock,(Boolean) async);
  25005. æRI II-113, IV-143
  25006. æC 
  25007. Trap macro    _Allocate
  25008.  
  25009. Parameter block
  25010.   -->    12    ioCompletion  pointer
  25011.   <--    16    ioResult      word
  25012.   -->    24    ioRefNum      word
  25013.   -->    36    ioReqCount    long word
  25014.   <--    40    ioActCount    long word
  25015.  
  25016. PBAllocate adds ioReqCount bytes to the open file whose access path is specified by
  25017. ioRefNum, and sets the physical end-of-file to one byte beyond the last block allocated.
  25018. The number of bytes actually allocated is rounded up to the nearest multiple of the
  25019. allocation block size, and returned in ioActCount. If there isn’t enough empty space
  25020. on the volume to satisfy the allocation request, PBAllocate allocates the rest of the
  25021. space on the volume and returns dskFulErr as its function result.
  25022.  
  25023. Note:  Even if the total number of requested bytes is unavailable,
  25024.        PBAllocate will allocate whatever space, contiguous or not, is
  25025.        available. To force the allocation of the entire requested space
  25026.        as a contiguous piece, call PBAllocContig instead.
  25027.  
  25028. Result codes    noErr      No error
  25029.                 dskFulErr  Disk full
  25030.                 fLckdErr   File locked
  25031.                 fnOpnErr   File not open
  25032.                 ioErr      I/O error
  25033.                 rfNumErr   Bad reference number
  25034.                 vLckdErr   Software volume lock
  25035.                 wPrErr     Hardware volume lock
  25036.                 wrPermErr  Read/write permission doesn’t allow writing
  25037.     wrPermErr   Read/write permission doesn’t allow writing
  25038.  
  25039. æKY PBGetEOF
  25040. æFc Files.h
  25041. æT Function
  25042. æD pascal OSErr PBGetEOF(ParmBlkPtr paramBlock,Boolean async); 
  25043. æDT OSErr myVariable = PBGetEOF((ParmBlkPtr) paramBlock,(Boolean) async);
  25044. æRI II-112, IV-142
  25045. æC 
  25046. Trap macro    _GetEOF
  25047.  
  25048. Parameter block
  25049.   -->    12    ioCompletion  pointer
  25050.   <--    16    ioResult      word
  25051.   -->    24    ioRefNum      word
  25052.   <--    28    ioMisc        long word
  25053.  
  25054. PBGetEOF returns, in ioMisc, the logical end-of-file of the open file whose access
  25055. path is specified by ioRefNum.
  25056.  
  25057. Result codes    noErr     No error
  25058.                 extFSErr  External file system
  25059.                 fnOpnErr  File not open
  25060.                 ioErr     I/O error
  25061.                 rfNumErr  Bad reference number
  25062.  
  25063. æKY PBSetEOF
  25064. æFc Files.h
  25065. æT Function
  25066. æD pascal OSErr PBSetEOF(ParmBlkPtr paramBlock,Boolean async); 
  25067. æDT OSErr myVariable = PBSetEOF((ParmBlkPtr) paramBlock,(Boolean) async);
  25068. æRI II-112, IV-142
  25069. æC 
  25070. Trap macro    _SetEOF
  25071.  
  25072. Parameter block
  25073.   -->    12    ioCompletion  pointer
  25074.   <--    16    ioResult      word
  25075.   -->    24    ioRefNum      word
  25076.   -->    28    ioMisc        long word
  25077.  
  25078. PBSetEOF sets the logical end-of-file of the open file, whose access path is specified
  25079. by ioRefNum, to ioMisc. If you attempt to set the logical end-of-file beyond the
  25080. physical end-of-file, another allocation block is added to the file; if there isn’t
  25081. enough space on the volume, no change is made, and PBSetEOF returns dskFulErr as its
  25082. function result. If ioMisc is 0, all space occupied by the file on the volume is
  25083. released.
  25084.  
  25085. Result codes    noErr      No error
  25086.                 dskFulErr  Disk full
  25087.                 extFSErr   External file system
  25088.                 fLckdErr   File locked
  25089.                 fnOpnErr   File not open
  25090.                 ioErr      I/O error
  25091.                 rfNumErr   Bad reference number
  25092.                 vLckdErr   Software volume lock
  25093.                 wPrErr     Hardware volume lock
  25094.                 wrPermErr  Read/write permission doesn’t allow writing
  25095.  
  25096. æKY PBGetFPos
  25097. æFc Files.h
  25098. æT Function
  25099. æD pascal OSErr PBGetFPos(ParmBlkPtr paramBlock,Boolean async); 
  25100. æDT OSErr myVariable = PBGetFPos((ParmBlkPtr) paramBlock,(Boolean) async);
  25101. æRI II-111, IV-141
  25102. æC 
  25103. Trap macro    _GetFPos
  25104.  
  25105. Parameter block
  25106.   -->    12    ioCompletion  pointer
  25107.   <--    16    ioResult      word
  25108.   -->    24    ioRefNum      word
  25109.   <--    36    ioReqCount    long word
  25110.   <--    40    ioActCount    long word
  25111.   <--    44    ioPosMode     word
  25112.   <--    46    ioPosOffset   long word
  25113.  
  25114. PBGetFPos returns, in ioPosOffset, the mark of the open file whose access path is
  25115. specified by ioRefNum. It sets ioReqCount, ioActCount, and ioPosMode to 0.
  25116.  
  25117. Result codes    noErr     No error
  25118.                 extFSErr  External file system
  25119.                 fnOpnErr  File not open
  25120.                 gfpErr    Error during GetFPos
  25121.                 ioErr     I/O error
  25122.                 rfNumErr  Bad reference number
  25123.  
  25124. æKY PBSetFPos
  25125. æFc Files.h
  25126. æT Function
  25127. æD pascal OSErr PBSetFPos(ParmBlkPtr paramBlock,Boolean async); 
  25128. æDT OSErr myVariable = PBSetFPos((ParmBlkPtr) paramBlock,(Boolean) async);
  25129. æRI II-111, IV-141
  25130. æC 
  25131. Trap macro    _SetFPos
  25132.  
  25133. Parameter block
  25134.   -->    12    ioCompletion  pointer
  25135.   <--    16    ioResult      word
  25136.   -->    24    ioRefNum      word
  25137.   -->    44    ioPosMode     word
  25138.   <->    46    ioPosOffset   long word
  25139.  
  25140. PBSetFPos sets the mark of the open file whose access path is specified by ioRefNum
  25141. to the position specified by ioPosMode and ioPosOffset. The position at which the
  25142. mark is actually set is returned in ioPosOffset. If you try to set the mark past the
  25143. logical end-of-file, PBSetFPos moves the mark to the end-of-file and returns eofErr
  25144. as its function result.
  25145.  
  25146. Result codes    noErr     No error
  25147.                 eofErr    End-of-file
  25148.                 extFSErr  External file system
  25149.                 fnOpnErr  File not open
  25150.                 ioErr     I/O error
  25151.                 posErr    Attempt to position before start of file
  25152.                 rfNumErr  Bad reference number
  25153.  
  25154. æKY PBFlushFile
  25155. æFc Files.h
  25156. æT Function
  25157. æD pascal OSErr PBFlushFile(ParmBlkPtr paramBlock,Boolean async); 
  25158. æDT OSErr myVariable = PBFlushFile((ParmBlkPtr) paramBlock,(Boolean) async);
  25159. æRI II-114, IV-144
  25160. æC 
  25161. Trap macro    _FlushFile
  25162.  
  25163. Parameter block
  25164.   -->    12    ioCompletion  pointer
  25165.   <--    16    ioResult      word
  25166.   -->    24    ioRefNum      word
  25167.  
  25168. PBFlushFile writes the contents of the access path buffer indicated by ioRefNum to
  25169. the volume, and updates the file’s entry in the file directory (or in the file catalog,
  25170. in the case of hierarchical volumes).
  25171.  
  25172. Warning:  Some information stored on the volume won’t be correct
  25173.           until PBFlushVol is called.
  25174.  
  25175. Result codes    noErr      No error
  25176.                 extFSErr   External file system
  25177.                 fnfErr     File not found
  25178.                 fnOpnErr   File not open
  25179.                 ioErr      I/O error
  25180.                 nsvErr     No such volume
  25181.                 rfNumErr   Bad reference number
  25182.  
  25183. æKY PBMountVol
  25184. æFc Files.h
  25185. æT Function
  25186. æD pascal OSErr PBMountVol(ParmBlkPtr paramBlock); 
  25187. æDT OSErr myVariable = PBMountVol((ParmBlkPtr) paramBlock);
  25188. æMM
  25189. æRT 134
  25190. æRI II-103, IV-128
  25191. æC 
  25192. »Accessing Volumes
  25193.  
  25194. To get the volume reference number of a volume, given the path reference number of a
  25195. file on that volume, both Pascal and assembly-language programmers can call the
  25196. high-level File Manager function GetVRefNum. Assembly-language programmers may prefer
  25197. calling the function GetFCBInfo (described below in the section “Data Structures in
  25198. Memory”).
  25199.  
  25200. FUNCTION PBMountVol (paramBlock:  ParmBlkPtr) :  OSErr;
  25201.  
  25202. Trap macro    _MountVol
  25203.  
  25204. Parameter block
  25205.   <--    16    ioResult   word
  25206.   <->    22    ioVRefNum  word
  25207.  
  25208. PBMountVol mounts the volume in the drive specified by ioVRefNum, and returns a
  25209. volume reference number in ioVRefNum. If there are no volumes already mounted, this
  25210. volume becomes the default volume. PBMountVol is always executed synchronously.
  25211.  
  25212. Note:  When mounting hierarchical volumes, PBMountVol opens two files
  25213.        needed for maintaining file directory and file mapping information.
  25214.        PBMountVol can fail if there are no access paths available for these
  25215.        two files; it will return tmfoErr as its function result.
  25216.  
  25217. Result codes    noErr        No error
  25218.                 badMDBErr    Bad master directory block
  25219.                 extFSErr     External file system
  25220.                 ioErr        I/O error
  25221.                 memFullErr   Not enough room in heap zone
  25222.                 noMacDskErr  Not a Macintosh disk
  25223.                 nsDrvErr     No such drive
  25224.                 paramErr     Bad drive number
  25225.                 tmfoErr      Too many files open
  25226.                 volOnLinErr  Volume already on-line
  25227.  
  25228. æKY PBUnmountVol
  25229. æFc Files.h
  25230. æT Function
  25231. æD pascal OSErr PBUnmountVol(ParmBlkPtr paramBlock); 
  25232. æDT OSErr myVariable = PBUnmountVol((ParmBlkPtr) paramBlock);
  25233. æRI II-106, IV-134
  25234. æC 
  25235. Trap macro    _UnmountVol
  25236.  
  25237. Parameter block
  25238.   <--    16    ioResult   word
  25239.   -->    18    ioNamePtr  pointer
  25240.   -->    22    ioVRefNum  word
  25241.  
  25242. PBUnmountVol unmounts the volume specified by ioNamePtr or ioVRefNum, by calling
  25243. PBFlushVol to flush the volume, closing all open files on the volume, and releasing
  25244. the memory used for the volume. PBUnmountVol is always executed synchronously.
  25245.  
  25246. Warning:  Don’t unmount the startup volume.
  25247.  
  25248. Note:  Unmounting a volume does not close working directories; to release
  25249.        the memory allocated to a working directory, call PBCloseWD.
  25250.  
  25251. Result codes    noErr     No error
  25252.                 bdNamErr  Bad volume name
  25253.                 extFSErr  External file system
  25254.                 ioErr     I/O error
  25255.                 nsDrvErr  No such drive
  25256.                 nsvErr    No such volume
  25257.                 paramErr  No default volume
  25258.  
  25259. æKY PBEject
  25260. æFc Files.h
  25261. æT Function
  25262. æD pascal OSErr PBEject(ParmBlkPtr paramBlock); 
  25263. æDT OSErr myVariable = PBEject((ParmBlkPtr) paramBlock);
  25264. æMM
  25265. æRI II-107, IV-135
  25266. æC 
  25267. Trap macro    _Eject
  25268.  
  25269. Parameter block
  25270.   -->    12    ioCompletion  pointer
  25271.   <--    16    ioResult      word
  25272.   -->    18    ioNamePtr     pointer
  25273.   -->    22    ioVRefNum     word
  25274.  
  25275. PBEject flushes the volume specified by ioNamePtr or ioVRefNum, places it
  25276. off-line, and then ejects the volume.
  25277.  
  25278. Assembly-language note:  You may invoke the macro _Eject asynchronously;
  25279.                          the first part of the call is executed synchronously,
  25280.                          and the actual ejection is executed asynchronously.
  25281.  
  25282. Result codes    noErr     No error
  25283.                 bdNamErr  Bad volume name
  25284.                 extFSErr  External file system
  25285.                 ioErr     I/O error
  25286.                 nsDrvErr  No such drive
  25287.                 nsvErr    No such volume
  25288.                 paramErr  No default volume
  25289.  
  25290. æKY PBOffLine
  25291. æFc Files.h
  25292. æT Function
  25293. æD pascal OSErr PBOffLine(ParmBlkPtr paramBlock); 
  25294. æDT OSErr myVariable = PBOffLine((ParmBlkPtr) paramBlock);
  25295. æMM
  25296. æRI II-106, IV-134
  25297. æC 
  25298. Trap macro    _OffLine
  25299.  
  25300. Parameter block
  25301.   -->    12    ioCompletion  pointer
  25302.   <--    16    ioResult      word
  25303.   -->    18    ioNamePtr     pointer
  25304.   -->    22    ioVRefNum     word
  25305.  
  25306. PBOffLine places off-line the volume specified by ioNamePtr or ioVRefNum, by calling
  25307. PBFlushVol to flush the volume and releasing all the memory used for the volume
  25308. except for the volume control block. PBOffLine is always executed synchronously.
  25309.  
  25310. Result codes    noErr     No error
  25311.                 bdNamErr  Bad volume name
  25312.                 extFSErr  External file system
  25313.                 ioErr     I/O error
  25314.                 nsDrvErr  No such drive
  25315.                 nsvErr    No such volume
  25316.                 paramErr  No default volume
  25317.  
  25318. æKY PBCatSearch
  25319. æFc Files.h
  25320. æT Function
  25321. æD pascal OSErr PBCatSearch(CSParamPtr paramBlock,Boolean async); 
  25322. æDT OSErr myVariable = PBCatSearch((CSParamPtr) paramBlock,(Boolean) async);
  25323. æMM
  25324. æRI VI
  25325. æC 
  25326. Parameter Block
  25327.   Æ   12  ioCompletion  pointer  pointer to completion routine
  25328.   ¨   16  ioResult         word         result code
  25329.   Æ   18  ioNamePtr        pointer      pointer to volume name
  25330.   Æ   22  ioVRefNum        word         vRefNum or WDRefNum
  25331.   Æ   24  FSSpecArrayPtr   pointer      pointer to array of matches
  25332.   Æ   28  ioReqMatchCount  long         maximum match count wanted
  25333.   ¨   32  ioActMatchCount  long         actual match count 
  25334.   Æ   36  ioSpecBits       long         enable bits for fields in ioSpecs
  25335.   Æ   40  ioSpec1          CinfoPBPtr   values and lower bounds
  25336.   Æ   44  ioSpec2          CinfoPBPtr   masks and upper bounds
  25337.   Æ   48  ioSearchTime     long         maximum elapsed search time
  25338.   Æ   52  ioCatPosition    CatPosition  current catalog position
  25339.   Æ   56  ioRBuffer        pointer      pointer to optional read buffer
  25340.   Æ   60  ioRBufLen        long         length of optional read buffer
  25341.  
  25342. PBCatSearch searches the volume you specify in the parameter block for files
  25343. that match two coordinated sets of selection criteria. PBCatSearch returns the
  25344. names and directory IDs for the files and directories that match the criteria in
  25345. an array of IDs and names.
  25346.  
  25347. Parameter          Meaning
  25348.  
  25349. ioCompletion       A pointer to the completion routine.
  25350.  
  25351. ioResult           Result code.
  25352.  
  25353. ioNamePtr          Pointer to volume name.
  25354.  
  25355. ioFSSpecArrayPtr   A pointer to an array where the file and directory names that
  25356.                    match the selection criteria are returned.
  25357.  
  25358. ioReqMatchCount    The approximate maximum number of matches to return in the
  25359.                    ioReqMatchCount field. Use this field to avoid a possible
  25360.                    glut of matches for criteria that prove to be too general.
  25361.  
  25362. ioActMatchCount    The number of actual matches found.
  25363.  
  25364. ioSpecBits         The fields of the parameter blocks ioSpec1 and ioSpec2 that
  25365.                    are relevant to the search. See “Searching a Volume” for the
  25366.                    values of ioSpecBits.
  25367.  
  25368. ioSpec1            A pointer to a CInfoPBRec parameter block that contains 
  25369.                    values and the lower bounds of ranges for the fields selected
  25370.                    by ioSpecBits.
  25371.  
  25372. ioSpec2            A pointer to a second CInfoPBRec parameter block that 
  25373.                    contains masks and upper bounds of ranges for the fields 
  25374.                    selected by ioSpecBits.
  25375.  
  25376. ioSearchTime       A time limit on the time taken for a search. Use this field
  25377.                    to limit the run time of a single call to PBCatSearch.
  25378.  
  25379. ioCatPosition      A position in the catalog where searching should begin. Use
  25380.                    this field to keep an index into the catalog when breaking 
  25381.                    PBCatSearch down into a number of shorter searches.
  25382.  
  25383.                    To start at the beginning of the catalog, set ioCatPosition 
  25384.                    to 0. Before exiting after an interrupted search, PBCatSearch
  25385.                    sets it to the next record to be searched. To resume where 
  25386.                    the previous call stopped, pass the output of the previous 
  25387.                    call as input to the next.
  25388.  
  25389. ioRBuffer          A pointer to an optional read buffer. The ioRBuffer and 
  25390.                    ioRBufferLen fields let you specify a part of memory as a 
  25391.                    read buffer, increasing search speed.
  25392.  
  25393. ioRBufLen          The length of the buffer pointed to by ioRBuffer. Buffer
  25394.                    effectiveness varies with models and configurations, but a 32
  25395.                    KB buffer is likely to be optimal. Even a 1 KB buffer 
  25396.                    provides some performance improvement.
  25397.  
  25398. See the section “Using the File Manager” for a more complete description of
  25399. PBCatSearch.
  25400.  
  25401. Result codes
  25402.  
  25403. noErr                No error
  25404. extFSErr             External file system
  25405. ioErr                I/O error
  25406. nsvErr               No such volume
  25407. catalogChangedErr    The catalog has changed and CatPosition may be invalid
  25408. paramErr             Numerous causes
  25409.  
  25410. æKY AddDrive
  25411. æFc Files.h
  25412. æT Function
  25413. æD pascal void AddDrive(short drvrRefNum,short drvNum,DrvQElPtr qEl); 
  25414. æDT AddDrive((short) drvrRefNum,(short) drvNum,(DrvQElPtr) qEl);
  25415. æRT 36, 108 
  25416. æRI N36, N108-1
  25417. æC 
  25418.  
  25419. æKY FSOpen
  25420. æFc Files.h
  25421. æT Function
  25422. æD pascal OSErr FSOpen(const Str255 fileName,short vRefNum,short *refNum); 
  25423. æDT OSErr myVariable = FSOpen((const Str255) fileName,(short) vRefNum,(short *) refNum);
  25424. æRT 102
  25425. æRI II-91, IV-109, P-131, 171
  25426. æC  
  25427. [Not in ROM]
  25428.  
  25429. FSOpen creates an access path to the file having the name fileName on the volume
  25430. specified by vRefNum. A path reference number is returned in refNum. The access
  25431. path’s read/write permission is set to whatever the file’s open permission allows.
  25432.  
  25433. Note:  There’s no guarantee that any bytes have been written until
  25434.        FlushVol is called.
  25435.  
  25436. Result codes    noErr       No error
  25437.                 bdNamErr    Bad file name
  25438.                 extFSErr    External file system
  25439.                 fnfErr      File not found
  25440.                 ioErr       I/O error
  25441.                 nsvErr      No such volume
  25442.                 opWrErr     File already open for writing
  25443.                 tmfoErr     Too many files open
  25444.  
  25445. æKY fsopen
  25446. æFc Files.h
  25447. æT Function
  25448. æD OSErr fsopen(char *fileName,short vRefNum,short *refNum); 
  25449. æDT OSErr myVariable = fsopen((char *) fileName,(short) vRefNum,(short *) refNum);
  25450. æC 
  25451.  
  25452. æKY FSClose
  25453. æFc Files.h
  25454. æT Function
  25455. æD pascal OSErr FSClose(short refNum); 
  25456. æDT OSErr myVariable = FSClose((short) refNum);
  25457. æRT 102
  25458. æRI II-94, IV-112, P-132, 133, 171
  25459. æC  
  25460. [Not in ROM]
  25461.  
  25462. FSClose removes the access path specified by refNum, writes the contents of the
  25463. volume buffer to the volume, and updates the file’s entry in the file directory.
  25464.  
  25465. Note:  There’s no guarantee that any bytes have been written until
  25466.        FlushVol is called.
  25467.  
  25468. Result codes    noErr       No error
  25469.                 extFSErr    External file system
  25470.                 fnfErr      File not found
  25471.                 fnOpnErr    File not open
  25472.                 ioErr       I/O error
  25473.                 nsvErr      No such volume
  25474.                 rfNumErr    Bad reference number
  25475.  
  25476. æKY FSRead
  25477. æFc Files.h
  25478. æT Function
  25479. æD pascal OSErr FSRead(short refNum,long *count,Ptr buffPtr); 
  25480. æDT OSErr myVariable = FSRead((short) refNum,(long *) count,(Ptr) buffPtr);
  25481. æRI IV-109, P-131, 171
  25482. æC  
  25483. [Not in ROM]
  25484.  
  25485. FSRead attempts to read the number of bytes specified by the count parameter from the
  25486. open file whose access path is specified by refNum, and transfer them to the data
  25487. buffer pointed to by buffPtr. The read operation begins at the current mark, so you
  25488. might want to precede this with a call to SetFPos. If you try to read past the logical
  25489. end-of-file, FSRead moves the mark to the end-of-file and returns eofErr as its
  25490. function result. After the read is completed, the number of bytes actually read is
  25491. returned in the count parameter.
  25492.  
  25493. Result codes    noErr       No error
  25494.                 eofErr      End-of-file
  25495.                 extFSErr    External file system
  25496.                 fnOpnErr    File not open
  25497.                 ioErr       I/O error
  25498.                 paramErr    Negative count
  25499.                 rfNumErr    Bad reference number
  25500.  
  25501. æKY FSWrite
  25502. æFc Files.h
  25503. æT Function
  25504. æD pascal OSErr FSWrite(short refNum,long *count,Ptr buffPtr); 
  25505. æDT OSErr myVariable = FSWrite((short) refNum,(long *) count,(Ptr) buffPtr);
  25506. æRI IV-110, P-132, 171
  25507. æC  
  25508. [Not in ROM]
  25509.  
  25510. FSWrite takes the number of bytes specified by the count parameter from the buffer
  25511. pointed to by buffPtr and attempts to write them to the open file whose access path
  25512. is specified by refNum. The write operation begins at the current mark, so you might
  25513. want to precede this with a call to SetFPos. After the write is completed, the number
  25514. of bytes actually written is returned in the count parameter.
  25515.  
  25516. Result codes    noErr        No error
  25517.                 dskFulErr    Disk full
  25518.                 fLckdErr     File locked
  25519.                 fnOpnErr     File not open
  25520.                 ioErr        I/O error
  25521.                 paramErr     Negative count
  25522.                 rfNumErr     Bad reference number
  25523.                 vLckdErr     Software volume lock
  25524.                 wPrErr       Hardware volume lock
  25525.                 wrPermErr    Read/write permission doesn’t allow writing
  25526.  
  25527. æKY GetVInfo
  25528. æFc Files.h
  25529. æT Function
  25530. æD pascal OSErr GetVInfo(short drvNum,StringPtr volName,short *vRefNum,long *freeBytes); 
  25531. æDT OSErr myVariable = GetVInfo((short) drvNum,(StringPtr) volName,(short *) vRefNum,(long *) freeBytes);
  25532. æRT 157
  25533. æRI II-89, IV-107, N157, low-level  II-104, IV-129
  25534. æC 
  25535. »Accessing Volumes
  25536.  
  25537. •••Refer to Technical Note #24:•••
  25538.  
  25539. FUNCTION GetVInfo (drvNum:  INTEGER; volName:  StringPtr; VAR vRefNum:  INTEGER;
  25540.                    VAR freeBytes:  LONGINT) :  OSErr; [Not in ROM]
  25541.  
  25542. •••Refer to Technical Note #157:•••
  25543.  
  25544. GetVInfo returns the name, reference number, and available space (in bytes), in
  25545. volName, vRefNum, and freeBytes, for the volume in the drive specified by drvNum.
  25546.  
  25547. Result codes    noErr       No error
  25548.                 nsvErr      No default volume
  25549.                 paramErr    Bad drive number
  25550.  
  25551. æKY getvinfo
  25552. æFc Files.h
  25553. æT Function
  25554. æD OSErr getvinfo(short drvNum,char *volName,short *vRefNum,long *freeBytes); 
  25555. æDT OSErr myVariable = getvinfo((short) drvNum,(char *) volName,(short *) vRefNum,(long *) freeBytes);
  25556. æC 
  25557.  
  25558. æKY GetFInfo
  25559. æFc Files.h
  25560. æT Function
  25561. æD pascal OSErr GetFInfo(const Str255 fileName,short vRefNum,FInfo *fndrInfo); 
  25562. æDT OSErr myVariable = GetFInfo((const Str255) fileName,(short) vRefNum,(FInfo *) fndrInfo);
  25563. æRI II-95, IV-113
  25564. æC  
  25565. [Not in ROM]
  25566.  
  25567. For the file having the name fileName on the specified volume, GetFInfo returns
  25568. information used by the Finder in fndrInfo (see the section “Information Used by the
  25569. Finder”).
  25570.  
  25571. Result codes    noErr       No error
  25572.                 bdNamErr    Bad file name
  25573.                 extFSErr    External file system
  25574.                 fnfErr      File not found
  25575.                 ioErr       I/O error
  25576.                 nsvErr      No such volume
  25577.                 paramErr    No default volume
  25578.  
  25579. æKY getfinfo
  25580. æFc Files.h
  25581. æT Function
  25582. æD OSErr getfinfo(char *fileName,short vRefNum,FInfo *fndrInfo); 
  25583. æDT OSErr myVariable = getfinfo((char *) fileName,(short) vRefNum,(FInfo *) fndrInfo);
  25584. æC 
  25585.  
  25586. æKY GetVol
  25587. æFc Files.h
  25588. æT Function
  25589. æD pascal OSErr GetVol(StringPtr volName,short *vRefNum); 
  25590. æDT OSErr myVariable = GetVol((StringPtr) volName,(short *) vRefNum);
  25591. æRT 77,140
  25592. æRI N77-2, N140 high-level  II-89, IV-107  low-level  II-104, IV-131
  25593. æC  
  25594. [Not in ROM]
  25595.  
  25596. GetVol returns the name of the default volume in volName and its volume reference
  25597. number in vRefNum.
  25598.  
  25599. Result codes    noErr     No error
  25600.                 nsvErr    No such volume
  25601.  
  25602. æKY getvol
  25603. æFc Files.h
  25604. æT Function
  25605. æD OSErr getvol(char *volName,short *vRefNum); 
  25606. æDT OSErr myVariable = getvol((char *) volName,(short *) vRefNum);
  25607. æC 
  25608.  
  25609. æKY SetVol
  25610. æFc Files.h
  25611. æT Function
  25612. æD pascal OSErr SetVol(StringPtr volName,short vRefNum); 
  25613. æDT OSErr myVariable = SetVol((StringPtr) volName,(short) vRefNum);
  25614. æRI II-89, IV-107  low-level II-105, IV-132
  25615. æC  
  25616. [Not in ROM]
  25617.  
  25618. SetVol sets the default volume to the mounted volume specified by volName or vRefNum.
  25619.  
  25620. Result codes    noErr       No error
  25621.                 bdNamErr    Bad volume name
  25622.                 nsvErr      No such volume
  25623.                 paramErr    No default volume
  25624.  
  25625. æKY setvol
  25626. æFc Files.h
  25627. æT Function
  25628. æD OSErr setvol(char *volName,short vRefNum); 
  25629. æDT OSErr myVariable = setvol((char *) volName,(short) vRefNum);
  25630. æC 
  25631.  
  25632. æKY UnmountVol
  25633. æFc Files.h
  25634. æT Function
  25635. æD pascal OSErr UnmountVol(StringPtr volName,short vRefNum); 
  25636. æDT OSErr myVariable = UnmountVol((StringPtr) volName,(short) vRefNum);
  25637. æRT 180
  25638. æRI II-90, IV-108  low-level II-106, IV-134
  25639. æC  
  25640. [Not in ROM]
  25641.  
  25642. UnmountVol unmounts the volume specified by volName or vRefNum, by calling FlushVol
  25643. to flush the volume buffer, closing all open files on the volume, and releasing the
  25644. memory used for the volume.
  25645.  
  25646. Warning:  Don’t unmount the startup volume.
  25647.  
  25648. Result codes    noErr        No error
  25649.                 bdNamErr     Bad volume name
  25650.                 extFSErr     External file system
  25651.                 ioErr        I/O error
  25652.                 nsDrvErr     No such drive
  25653.                 nsvErr       No such volume
  25654.                 paramErr     No default volume
  25655.  
  25656. æKY unmountvol
  25657. æFc Files.h
  25658. æT Function
  25659. æD OSErr unmountvol(char *volName,short vRefNum); 
  25660. æDT OSErr myVariable = unmountvol((char *) volName,(short) vRefNum);
  25661. æC 
  25662.  
  25663. æKY Eject
  25664. æFc Files.h
  25665. æT Function
  25666. æD pascal OSErr Eject(StringPtr volName,short vRefNum); 
  25667. æDT OSErr myVariable = Eject((StringPtr) volName,(short) vRefNum);
  25668. æMM
  25669. æRI II-90, IV-108 low-level  II-107, IV-135
  25670. æC  
  25671. [Not in ROM]
  25672.  
  25673. Eject flushes the volume specified by volName or vRefNum, places it off-line, and
  25674. then ejects the volume.
  25675.  
  25676. Result codes    noErr       No error
  25677.                 bdNamErr    Bad volume name
  25678.                 extFSErr    External file system
  25679.                 ioErr       I/O error
  25680.                 nsDrvErr    No such drive
  25681.                 nsvErr      No such volume
  25682.                 paramErr    No default volume
  25683.  
  25684. æKY eject
  25685. æFc Files.h
  25686. æT Function
  25687. æD OSErr eject(char *volName,short vRefNum); 
  25688. æDT OSErr myVariable = eject((char *) volName,(short) vRefNum);
  25689. æC 
  25690.  
  25691. æKY FlushVol
  25692. æFc Files.h
  25693. æT Function
  25694. æD pascal OSErr FlushVol(StringPtr volName,short vRefNum); 
  25695. æDT OSErr myVariable = FlushVol((StringPtr) volName,(short) vRefNum);
  25696. æMM
  25697. æRI P-132, 133 high-level  II-89, IV-108 low-level  II-105, IV-133
  25698. æC  
  25699. [Not in ROM]
  25700.  
  25701. On the volume specified by volName or vRefNum, FlushVol writes the contents of the
  25702. associated volume buffer and descriptive information about the volume (if they’ve
  25703. changed since the last time FlushVol was called).
  25704.  
  25705. Result codes    noErr       No error
  25706.                 bdNamErr    Bad volume name
  25707.                 extFSErr    External file system
  25708.                 ioErr       I/O error
  25709.                 nsDrvErr    No such drive
  25710.                 nsvErr      No such volume
  25711.                 paramErr    No default volume
  25712.  
  25713. æKY flushvol
  25714. æFc Files.h
  25715. æT Function
  25716. æD OSErr flushvol(char *volName,short vRefNum); 
  25717. æDT OSErr myVariable = flushvol((char *) volName,(short) vRefNum);
  25718. æC 
  25719.  
  25720. æKY Create
  25721. æFc Files.h
  25722. æT Function
  25723. æD pascal OSErr Create(const Str255 fileName,short vRefNum,OSType creator,
  25724.     OSType fileType); 
  25725. æDT OSErr myVariable = Create((const Str255) fileName,(short) vRefNum,(OSType) creator,()
  25726.     OSType fileType);
  25727. æRI II-90, IV-112 low-level II-107, IV-145
  25728. æC  
  25729. [Not in ROM]
  25730.  
  25731. Create creates a new file (both forks) with the specified name, file type, and creator
  25732. on the specified volume. (File type and creator are discussed in the Finder Interface
  25733. chapter.) The new file is unlocked and empty. The date and time of its creation and
  25734. last modification are set to the current date and time.
  25735.  
  25736. Result codes    noErr        No error
  25737.                 bdNamErr     Bad file name
  25738.                 dupFNErr     Duplicate file name and version
  25739.                 dirFulErr    File directory full
  25740.                 extFSErr     External file system
  25741.                 ioErr        I/O error
  25742.                 nsvErr       No such volume
  25743.                 vLckdErr     Software volume lock
  25744.                 wPrErr       Hardware volume lock
  25745.  
  25746. æKY create
  25747. æFc Files.h
  25748. æT Function
  25749. æD OSErr create(char *fileName,short vRefNum,OSType creator,OSType fileType); 
  25750. æDT OSErr myVariable = create((char *) fileName,(short) vRefNum,(OSType) creator,(OSType) fileType);
  25751. æRI II-90, IV-112 low-level II-107, IV-145
  25752. æC     Create creates a new file (both forks) with the specified name,
  25753. file type, and creator on the specified volume. (File type and
  25754. creator are discussed in the Finder Interface chapter.)
  25755. The new file is unlocked and empty. The date and time of its
  25756. creation and last modification are set to the current date and time.
  25757.  
  25758. Result codes
  25759.  
  25760.     noErr       No error
  25761.     bdNamErr    Bad file name
  25762.     dupFNErr    Duplicate file name and version
  25763.     dirFulErr   File directory full
  25764.     extFSErr    External file system
  25765.     ioErr       I/O error
  25766.     nsvErr      No such volume
  25767.     vLckdErr    Software volume lock
  25768.     wPrErr      Hardware volume lock
  25769.  
  25770. æKY FSDelete
  25771. æFc Files.h
  25772. æT Function
  25773. æD pascal OSErr FSDelete(const Str255 fileName,short vRefNum); 
  25774. æDT OSErr myVariable = FSDelete((const Str255) fileName,(short) vRefNum);
  25775. æRI II-97, IV-113
  25776. æC 
  25777. [Not in ROM]
  25778.  
  25779. FSDelete removes the closed file having the name fileName from the specified volume.
  25780.  
  25781. Note:  This function will delete both forks of a file.
  25782.  
  25783. Result codes    noErr       No error
  25784.                 bdNamErr    Bad file name
  25785.                 extFSErr    External file system
  25786.                 fBsyErr     File busy
  25787.                 fLckdErr    File locked
  25788.                 fnfErr      File not found
  25789.                 ioErr       I/O error
  25790.                 nsvErr      No such volume
  25791.                 vLckdErr    Software volume lock
  25792.                 wPrErr      Hardware volume lock
  25793.  
  25794. æKY fsdelete
  25795. æFc Files.h
  25796. æT Function
  25797. æD OSErr fsdelete(char *fileName,short vRefNum); 
  25798. æDT OSErr myVariable = fsdelete((char *) fileName,(short) vRefNum);
  25799. æC 
  25800.  
  25801. æKY OpenRF
  25802. æFc Files.h
  25803. æT Function
  25804. æD pascal OSErr OpenRF(const Str255 fileName,short vRefNum,short *refNum); 
  25805. æDT OSErr myVariable = OpenRF((const Str255) fileName,(short) vRefNum,(short *) refNum);
  25806. æRT 74
  25807. æRI II-91, IV-109 low-level II-109, IV-137
  25808. æC  
  25809. [Not in ROM]
  25810.  
  25811. OpenRF is similar to FSOpen; the only difference is that OpenRF opens the resource
  25812. fork of the specified file rather than the data fork. A path reference number is
  25813. returned in refNum. The access path’s read/write permission is set to whatever the
  25814. file’s open permission allows.
  25815.  
  25816. Note:  Normally you should access a file’s resource fork through the
  25817.        routines of the Resource Manager rather than the File Manager.
  25818.        OpenRF doesn’t read the resource map into memory; it’s really
  25819.        only useful for block-level operations such as copying files.
  25820.  
  25821. Result codes    noErr       No error
  25822.                 bdNamErr    Bad file name
  25823.                 extFSErr    External file system
  25824.                 fnfErr      File not found
  25825.                 ioErr       I/O error
  25826.                 nsvErr      No such volume
  25827.                 opWrErr     File already open for writing
  25828.                 tmfoErr     Too many files open
  25829.  
  25830. æKY openrf
  25831. æFc Files.h
  25832. æT Function
  25833. æD OSErr openrf(char *fileName,short vRefNum,short *refNum); 
  25834. æDT OSErr myVariable = openrf((char *) fileName,(short) vRefNum,(short *) refNum);
  25835. æC 
  25836.  
  25837. æKY Rename
  25838. æFc Files.h
  25839. æT Function
  25840. æD pascal OSErr Rename(const Str255 oldName,short vRefNum,const Str255 newName); 
  25841. æDT OSErr myVariable = Rename((const Str255) oldName,(short) vRefNum,(const Str255) newName);
  25842. æRI II-96, IV-114  low-level II-118, IV-153
  25843. æC  
  25844. [Not in ROM]
  25845.  
  25846. Given a file name in oldName, Rename changes the name of the file to newName. Access
  25847. paths currently in use aren’t affected. Given a volume name in oldName or a volume
  25848. reference number in vRefNum, Rename changes the name of the specified volume to
  25849. newName.
  25850.  
  25851. Warning:  If you’re renaming a volume, be sure that both names end with a colon.
  25852.  
  25853. Result codes    noErr        No error
  25854.                 bdNamErr     Bad file name
  25855.                 dirFulErr    Directory full
  25856.                 dupFNErr     Duplicate file name
  25857.                 extFSErr     External file system
  25858.                 fLckdErr     File locked
  25859.                 fnfErr       File not found
  25860.                 fsRnErr      Problem during rename
  25861.                 ioErr        I/O error
  25862.                 nsvErr       No such volume
  25863.                 paramErr     No default volume
  25864.                 vLckdErr     Software volume lock
  25865.                 wPrErr       Hardware volume lock
  25866.  
  25867. æKY fsrename
  25868. æFc Files.h
  25869. æT Function
  25870. æD OSErr fsrename(char *oldName,short vRefNum,char *newName); 
  25871. æDT OSErr myVariable = fsrename((char *) oldName,(short) vRefNum,(char *) newName);
  25872. æRI II-96, IV-114  low-level II-118, IV-153
  25873. æC fsrename is actually the "c" version of the Macintosh ROM call, Rename,
  25874. which uses c strings. It was not named "rename" to avoid conflict 
  25875. with the ANSI call by that name.
  25876.  
  25877. æKY SetFInfo
  25878. æFc Files.h
  25879. æT Function
  25880. æD pascal OSErr SetFInfo(const Str255 fileName,short vRefNum,const FInfo *fndrInfo); 
  25881. æDT OSErr myVariable = SetFInfo((const Str255) fileName,(short) vRefNum,(const FInfo *) fndrInfo);
  25882. æRI II-95, IV-114
  25883. æC  
  25884. [Not in ROM]
  25885.  
  25886. For the file having the name fileName on the specified volume, SetFInfo sets information
  25887. used by the Finder to fndrInfo (see the section “Information Used by the Finder”).
  25888.  
  25889. Result codes    noErr        No error
  25890.                 extFSErr     External file system
  25891.                 fLckdErr     File locked
  25892.                 fnfErr       File not found
  25893.                 ioErr        I/O error
  25894.                 nsvErr       No such volume
  25895.                 vLckdErr     Software volume lock
  25896.                 wPrErr       Hardware volume lock
  25897.  
  25898. æKY setfinfo
  25899. æFc Files.h
  25900. æT Function
  25901. æD OSErr setfinfo(char *fileName,short vRefNum,FInfo *fndrInfo); 
  25902. æDT OSErr myVariable = setfinfo((char *) fileName,(short) vRefNum,(FInfo *) fndrInfo);
  25903. æC 
  25904.  
  25905. æKY SetFLock
  25906. æFc Files.h
  25907. æT Function
  25908. æD pascal OSErr SetFLock(const Str255 fileName,short vRefNum); 
  25909. æDT OSErr myVariable = SetFLock((const Str255) fileName,(short) vRefNum);
  25910. æRI II-95, IV-114
  25911. æC  
  25912. [Not in ROM]
  25913.  
  25914. SetFLock locks the file having the name fileName on the specified volume. Access
  25915. paths currently in use aren’t affected.
  25916.  
  25917. Result codes    noErr       No error
  25918.                 extFSErr    External file system
  25919.                 fnfErr      File not found
  25920.                 ioErr       I/O error
  25921.                 nsvErr      No such volume
  25922.                 vLckdErr    Software volume lock
  25923.                 wPrErr      Hardware volume lock
  25924.  
  25925. æKY setflock
  25926. æFc Files.h
  25927. æT Function
  25928. æD OSErr setflock(char *fileName,short vRefNum); 
  25929. æDT OSErr myVariable = setflock((char *) fileName,(short) vRefNum);
  25930. æC 
  25931.  
  25932. æKY RstFLock
  25933. æFc Files.h
  25934. æT Function
  25935. æD pascal OSErr RstFLock(const Str255 fileName,short vRefNum); 
  25936. æDT OSErr myVariable = RstFLock((const Str255) fileName,(short) vRefNum);
  25937. æRI II-96, IV-114
  25938. æC 
  25939. [Not in ROM]
  25940.  
  25941. RstFLock unlocks the file having the name fileName on the specified volume. Access
  25942. paths currently in use aren’t affected.
  25943.  
  25944. Result codes    noErr       No error
  25945.                 extFSErr    External file system
  25946.                 fnfErr      File not found
  25947.                 ioErr       I/O error
  25948.                 nsvErr      No such volume
  25949.                 vLckdErr    Software volume lock
  25950.                 wPrErr      Hardware volume lock
  25951.  
  25952. æKY rstflock
  25953. æFc Files.h
  25954. æT Function
  25955. æD OSErr rstflock(char *fileName,short vRefNum); 
  25956. æDT OSErr myVariable = rstflock((char *) fileName,(short) vRefNum);
  25957. æC 
  25958.  
  25959. æKY Allocate
  25960. æFc Files.h
  25961. æT Function
  25962. æD pascal OSErr Allocate(short refNum,long *count); 
  25963. æDT OSErr myVariable = Allocate((short) refNum,(long *) count);
  25964. æRI IV-143
  25965. æC  
  25966. [Not in ROM]
  25967.  
  25968. Allocate adds the number of bytes specified by the count parameter to the open file
  25969. whose access path is specified by refNum, and sets the physical end-of-file to one
  25970. byte beyond the last block allocated. The number of bytes actually allocated is
  25971. rounded up to the nearest multiple of the allocation block size, and returned in the
  25972. count parameter. If there isn’t enough empty space on the volume to satisfy the
  25973. allocation request, Allocate allocates the rest of the space on the volume and returns
  25974. dskFulErr as its function result.
  25975.  
  25976. Result codes    noErr        No error
  25977.                 dskFulErr    Disk full
  25978.                 fLckdErr     File locked
  25979.                 fnOpnErr     File not open
  25980.                 ioErr        I/O error
  25981.                 rfNumErr     Bad reference number
  25982.                 vLckdErr     Software volume lock
  25983.                 wPrErr       Hardware volume lock
  25984.                 wrPermErr    Read/write permission doesn’t allow writing
  25985.  
  25986. æKY GetEOF
  25987. æFc Files.h
  25988. æT Function
  25989. æD pascal OSErr GetEOF(short refNum,long *logEOF); 
  25990. æDT OSErr myVariable = GetEOF((short) refNum,(long *) logEOF);
  25991. æRI P-132, 172  high-level  II-93, IV-111 low-level  II-112, IV-142
  25992. æC  
  25993. [Not in ROM]
  25994.  
  25995. GetEOF returns, in logEOF, the logical end-of-file of the open file whose access path
  25996. is specified by refNum.
  25997.  
  25998. Result codes    noErr       No error
  25999.                 extFSErr    External file system
  26000.                 fnOpnErr    File not open
  26001.                 ioErr       I/O error
  26002.                 rfNumErr    Bad reference number
  26003.  
  26004. æKY SetEOF
  26005. æFc Files.h
  26006. æT Function
  26007. æD pascal OSErr SetEOF(short refNum,long logEOF); 
  26008. æDT OSErr myVariable = SetEOF((short) refNum,(long) logEOF);
  26009. æRI P-132, 180 high-level II-93, IV-111  low-level II-112, IV-142
  26010. æC  
  26011. [Not in ROM]
  26012.  
  26013. SetEOF sets the logical end-of-file of the open file whose access path is specified
  26014. by refNum to the position specified by logEOF. If you attempt to set the logical
  26015. end-of-file beyond the physical end-of-file, the physical end-of-file is set to one
  26016. byte beyond the end of the next free allocation block; if there isn’t enough space on
  26017. the volume, no change is made, and SetEOF returns dskFulErr as its function result.
  26018. If logEOF is 0, all space occupied by the file on the volume is released.
  26019.  
  26020. Result codes    noErr        No error
  26021.                 dskFulErr    Disk full
  26022.                 extFSErr     External file system
  26023.                 fLckdErr     File locked
  26024.                 fnOpnErr     File not open
  26025.                 ioErr        I/O error
  26026.                 rfNumErr     Bad reference number
  26027.                 vLckdErr     Software volume lock
  26028.                 wPrErr       Hardware volume lock
  26029.                 wrPermErr    Read/write permission doesn’t allow writing
  26030.  
  26031. æKY GetFPos
  26032. æFc Files.h
  26033. æT Function
  26034. æD pascal OSErr GetFPos(short refNum,long *filePos); 
  26035. æDT OSErr myVariable = GetFPos((short) refNum,(long *) filePos);
  26036. æRI II-92, IV-110  low-level  II-111, IV-141
  26037. æC  
  26038. [Not in ROM]
  26039.  
  26040. GetFPos returns, in filePos, the mark of the open file whose access path is specified
  26041. by refNum.
  26042.  
  26043. Result codes    noErr        No error
  26044.                 extFSErr     External file system
  26045.                 fnOpnErr     File not open
  26046.                 ioErr        I/O error
  26047.                 rfNumErr     Bad reference number
  26048.  
  26049. æKY SetFPos
  26050. æFc Files.h
  26051. æT Function
  26052. æD pascal OSErr SetFPos(short refNum,short posMode,long posOff); 
  26053. æDT OSErr myVariable = SetFPos((short) refNum,(short) posMode,(long) posOff);
  26054. æRI P-131, 132, 180  high-level II-93, IV-110 low-level II-111, IV-141
  26055. æC  
  26056. [Not in ROM]
  26057.  
  26058. SetFPos sets the mark of the open file whose access path is specified by refNum to
  26059. the position specified by posMode and posOff (except when posMode is equal to fsAtMark,
  26060. in which case posOff is ignored). PosMode indicates how to position the mark; it must
  26061. contain one of the following values:
  26062.  
  26063. CONST  fsAtMark     = 0;    {at current mark}
  26064.        fsFromStart  = 1;    {set mark relative to beginning of file}
  26065.        fsFromLEOF   = 2;    {set mark relative to logical end-of-file}
  26066.        fsFromMark   = 3;    {set mark relative to current mark}
  26067.  
  26068. If you specify fsAtMark, posOffset is ignored and the mark is left wherever
  26069. it’s currently positioned. If you choose to set the mark (relative to either the
  26070. beginning of the file, the logical end-of-file, or the current mark), posOffset
  26071. specifies the byte offset from the chosen point (either positive or negative) where
  26072. the mark should be set. If you try to set the mark past the logical end-of-file,
  26073. SetFPos moves the mark to the end-of-file and returns eofErr as its function result.
  26074.  
  26075. Result codes    noErr        No error
  26076.                 eofErr       End-of-file
  26077.                 extFSErr     External file system
  26078.                 fnOpnErr     File not open
  26079.                 ioErr        I/O error
  26080.                 posErr       Attempt to position before start of file
  26081.                 rfNumErr     Bad reference number
  26082.  
  26083. æKY GetVRefNum
  26084. æFc Files.h
  26085. æT Function
  26086. æD pascal OSErr GetVRefNum(short fileRefNum,short *vRefNum); 
  26087. æDT OSErr myVariable = GetVRefNum((short) fileRefNum,(short *) vRefNum);
  26088. æRI II-89, IV-107
  26089. æC  
  26090. [Not in ROM]
  26091.  
  26092. Given a path reference number in pathRefNum, GetVRefNum returns the volume reference
  26093. number in vRefNum.
  26094.  
  26095. Result codes    noErr       No error
  26096.                 rfNumErr    Bad reference number
  26097.  
  26098. æKY PBOpenDF
  26099. æFc Files.h
  26100. æT Function
  26101. æD pascal OSErr PBOpenDF(ParmBlkPtr paramBlock,Boolean async); 
  26102. æDT OSErr myVariable = PBOpenDF((ParmBlkPtr) paramBlock,(Boolean) async);
  26103. æRI VI
  26104. æC 
  26105. OpenDF creates an access path to the data fork of a file. It is almost identical
  26106. to PBFSOpen, which is documented in the File Manager chapter of Volume IV. The
  26107. difference is that PBFSOpen can open both files and devices, but PBOpenDF can
  26108. open only files. Using OpenDF instead of FSOpen when your application is opening
  26109. a file prevents naming conflicts or ambiguities.
  26110.  
  26111. æKY PBOpenWD
  26112. æFc Files.h
  26113. æT Function
  26114. æD pascal OSErr PBOpenWD(WDPBPtr paramBlock,Boolean async); 
  26115. æDT OSErr myVariable = PBOpenWD((WDPBPtr) paramBlock,(Boolean) async);
  26116. æRT 77, 190
  26117. æRI IV-158, N77-1
  26118. æC 
  26119. Trap macro    _OpenWD
  26120.  
  26121. Parameter block
  26122.   -->    12    ioCompletion  pointer
  26123.   <--    16    ioResult      word
  26124.   -->    18    ioNamePtr     pointer
  26125.   <->    22    ioVRefNum     word
  26126.   -->    28    ioWDProcID    long word
  26127.   -->    48    ioWDDirID     long word
  26128.  
  26129. PBOpenWD takes the directory specified by ioVRefNum, ioWDDirID, and ioWDProcID and
  26130. makes it a working directory. (You can also specify the directory using a combination
  26131. of partial pathname and directory ID.) It returns a working directory reference
  26132. number in ioVRefNum that can be used in subsequent calls.
  26133.  
  26134. If a given directory has already been made a working directory using the same ioWDProcID,
  26135. no new working directory will be opened; instead, the existing working directory
  26136. reference number will be returned. If a given directory was already made a working
  26137. directory using a different ioWDProcID, a new working directory reference number is
  26138. returned.
  26139.  
  26140. Result codes    noErr       No error
  26141.                 tmwdoErr    Too many working directories open
  26142.  
  26143. æKY PBCloseWD
  26144. æFc Files.h
  26145. æT Function
  26146. æD pascal OSErr PBCloseWD(WDPBPtr paramBlock,Boolean async); 
  26147. æDT OSErr myVariable = PBCloseWD((WDPBPtr) paramBlock,(Boolean) async);
  26148. æRI IV-158      
  26149. æC 
  26150. Trap macro    _CloseWD
  26151.  
  26152. Parameter block
  26153.   -->    12    ioCompletion  pointer
  26154.   <--    16    ioResult      word
  26155.   -->    22    ioVRefNum     word
  26156.  
  26157. PBCloseWD releases the working directory whose working directory reference number is
  26158. specified in ioVRefNum.
  26159.  
  26160. Note:  If a volume reference number is specified in ioVRefNum, PBCloseWD
  26161.        does nothing.
  26162.  
  26163. Result codes    noErr     No error
  26164.                 nsvErr    No such volume
  26165.  
  26166. æKY PBHSetVol
  26167. æFc Files.h
  26168. æT Function
  26169. æD pascal OSErr PBHSetVol(WDPBPtr paramBlock,Boolean async); 
  26170. æDT OSErr myVariable = PBHSetVol((WDPBPtr) paramBlock,(Boolean) async);
  26171. æRT 140
  26172. æRI IV-133, N140
  26173. æC 
  26174. •••Refer to Technical Note #140:•••
  26175.  
  26176. Trap macro    _HSetVol
  26177.  
  26178. Parameter block
  26179.   -->    12    ioCompletion  pointer
  26180.   <--    16    ioResult      word
  26181.   -->    18    ioNamePtr     pointer
  26182.   -->    22    ioVRefNum     word
  26183.   -->    48    ioWDDirID     long word
  26184.  
  26185. PBHSetVol sets both the default volume and the default directory. The default directory
  26186. to be used can be specified by either a volume reference number or a working directory
  26187. reference number in ioVRefNum, a directory ID in ioWDDirID, or a pointer to a pathname
  26188. (possibly NIL) in ioNamePtr.
  26189.  
  26190. Note:  Both the default volume and the default directory are used in
  26191.        calls made with no volume name and a volume reference number of zero.
  26192.  
  26193. Result codes    noErr     No error
  26194.                 nsvErr    No default volume
  26195.  
  26196. æKY PBHGetVol
  26197. æFc Files.h
  26198. æT Function
  26199. æD pascal OSErr PBHGetVol(WDPBPtr paramBlock,Boolean async); 
  26200. æDT OSErr myVariable = PBHGetVol((WDPBPtr) paramBlock,(Boolean) async);
  26201. æRI IV-132 
  26202. æC 
  26203. Trap macro    _HGetVol
  26204.  
  26205. Parameter block
  26206.   -->    12    ioCompletion  pointer
  26207.   <--    16    ioResult      word
  26208.   <--    18    ioNamePtr     pointer
  26209.   <--    22    ioVRefNum     word
  26210.   <--    28    ioWDProcID    long word
  26211.   <--    32    ioWDVRefNum   word
  26212.   <--    48    ioWDDirID     long word
  26213.  
  26214. PBHGetVol returns the default volume and directory last set by either a PBSetVol or a
  26215. PBHSetVol call. The reference number of the default volume is returned in ioVRefNum.
  26216.  
  26217. Warning:  IOVRefNum will return a working directory reference number
  26218.           (instead of the volume reference number) if, in the last call
  26219.           to PBSetVol or PBHSetVol, a working directory reference number
  26220.           was passed in this field.
  26221.  
  26222. The volume reference number of the volume on which the default directory exists is
  26223. returned in ioWDVRefNum. The directory ID of the default directory is returned in
  26224. ioWDDirID.
  26225.  
  26226. Result codes    noErr     No error
  26227.                 nsvErr    No default volume
  26228.  
  26229. æKY PBCatMove
  26230. æFc Files.h
  26231. æT Function
  26232. æD pascal OSErr PBCatMove(CMovePBPtr paramBlock,Boolean async); 
  26233. æDT OSErr myVariable = PBCatMove((CMovePBPtr) paramBlock,(Boolean) async);
  26234. æRI IV-157, VI
  26235. æC 
  26236. Some existing HFS functions now support file IDs as appropriate, but their
  26237. interface remains stable. This section describes how they accommodate file IDs.
  26238.  
  26239. FUNCTION PBCatMove (paramBlock: HParamBlkPtr, async: Boolean) : OSErr;
  26240.  
  26241. If a file ID exists for the file being moved, the file ID remains with the file.
  26242.  
  26243.  
  26244. •••Refer to Technical Note #226:•••
  26245.  
  26246. Trap macro    _CatMove
  26247.  
  26248. Parameter block
  26249.   -->    12    ioCompletion  pointer
  26250.   <--    16    ioResult      word
  26251.   -->    18    ioNamePtr     pointer
  26252.   -->    22    ioVRefNum     word
  26253.   -->    28    ioNewName     pointer
  26254.   -->    36    ioNewDirID    long word
  26255.   -->    48    ioDirID       long word
  26256.  
  26257. PBCatMove moves files or directories from one directory to another. The name of the
  26258. file or directory to be moved is pointed to by ioNamePtr; ioVRefNum contains either
  26259. the volume reference number or working directory reference number. A directory ID can
  26260. be specified in ioDirID. The name and directory ID of the directory to which the file
  26261. or directory is to be moved are specified by ioNewName and ioNewDirID.
  26262.  
  26263. PBCatMove is strictly a file catalog operation; it does not actually change the
  26264. location of the file or directory on the disk. PBCatMove cannot move a file or directory
  26265. to another volume (that is, ioVRefNum is used in specifying both the source and the
  26266. destination). It also cannot be used to rename files or directories; for that, use
  26267. PBHRename.
  26268.  
  26269. Result codes    noErr      No error
  26270.                 badMovErr  Attempt to move into offspring
  26271.                 bdNamErr   Bad file name or attempt to move into a file
  26272.                 dupFNErr   Duplicate file name and version
  26273.                 fnfErr     File not found
  26274.                 ioErr      I/O error
  26275.                 nsvErr     No such volume
  26276.                 paramErr   No default volume
  26277.                 vLckdErr   Software volume lock
  26278.                 wPrErr     Hardware volume lock
  26279.  
  26280. æKY PBDirCreate
  26281. æFc Files.h
  26282. æT Function
  26283. æD pascal OSErr PBDirCreate(HParmBlkPtr paramBlock,Boolean async); 
  26284. æDT OSErr myVariable = PBDirCreate((HParmBlkPtr) paramBlock,(Boolean) async);
  26285. æRI IV-146
  26286. æC 
  26287. Trap macro    _DirCreate
  26288.  
  26289. Parameter block
  26290.   -->    12    ioCompletion  pointer
  26291.   <--    16    ioResult      word
  26292.   <->    18    ioNamePtr     pointer
  26293.   -->    22    ioVRefNum     word
  26294.   <->    48    ioDirID       long word
  26295.  
  26296. PBDirCreate is identical to PBHCreate except that it creates a new directory instead
  26297. of a file. You can specify the parent of the directory to be created in ioDirID; if
  26298. it’s 0, the new directory will be placed in the root directory. The directory ID of
  26299. the new directory is returned in ioDirID.
  26300.  
  26301. Warning:  PBDirCreate operates only with the hierarchical version of
  26302.           the File Manager; if used on a Macintosh equipped only with
  26303.           the 64K ROM version of the File Manager, it will generate a
  26304.           system error.
  26305.  
  26306. Result codes    noErr      No error
  26307.                 bdNamErr   Bad file name
  26308.                 dupFNErr   Duplicate file name and version
  26309.                 dirFulErr  File directory full
  26310.                 dirNFErr   Directory not found or incomplete pathname
  26311.                 extFSErr   External file system
  26312.                 ioErr      I/O error
  26313.                 nsvErr     No such volume
  26314.                 vLckdErr   Software volume lock
  26315.                 wPrErr     Hardware volume lock
  26316.     
  26317.  
  26318. æKY PBGetWDInfo
  26319. æFc Files.h
  26320. æT Function
  26321. æD pascal OSErr PBGetWDInfo(WDPBPtr paramBlock,Boolean async); 
  26322. æDT OSErr myVariable = PBGetWDInfo((WDPBPtr) paramBlock,(Boolean) async);
  26323. æRT 77, 190
  26324. æRI IV-159, N77-5
  26325. æC 
  26326. Trap macro    _GetWDInfo
  26327.  
  26328. Parameter block
  26329.   -->    12    ioCompletion  pointer
  26330.   <--    16    ioResult      word
  26331.   <--    18    ioNamePtr     pointer
  26332.   <->    22    ioVRefNum     word
  26333.   -->    26    ioWDIndex     word
  26334.   <->    28    ioWDProcID    long word
  26335.   <->    32    ioWDVRefNum   word
  26336.   <--    48    ioWDDirID     long word
  26337.  
  26338. PBGetWDInfo returns information about the specified working directory. The working
  26339. directory can be specified either by its working directory reference number in ioVRefNum
  26340. (in which case ioWDIndex should be 0), or by its index number in ioWDIndex. In the
  26341. latter case, if ioVRefNum is nonzero, it’s interpreted as a volume specification
  26342. (volume reference number or drive number), and only working directories on that
  26343. volume are indexed.
  26344.  
  26345. IOWDVRefNum always returns the volume reference number. IOVRefNum returns a working
  26346. directory reference number when a working directory reference number is passed in
  26347. that field; otherwise, it returns a volume reference number. The volume name is
  26348. returned in ioNamePtr.
  26349.  
  26350. If IOWDProcID is nonzero, only working directories with that identifier are indexed;
  26351. otherwise all working directories are indexed.
  26352.  
  26353. Result codes    noErr     No error
  26354.                 nsvErr    No such volume
  26355.  
  26356. æKY PBGetFCBInfo
  26357. æFc Files.h
  26358. æT Function
  26359. æD pascal OSErr PBGetFCBInfo(FCBPBPtr paramBlock,Boolean async); 
  26360. æDT OSErr myVariable = PBGetFCBInfo((FCBPBPtr) paramBlock,(Boolean) async);
  26361. æRT 87
  26362. æRI IV-179, N87-1
  26363. æC  
  26364. Trap macro    _GetFCBInfo
  26365.  
  26366. Parameter block
  26367.   -->    12    ioCompletion  pointer
  26368.   <--    16    ioResult      word
  26369.   <--    18    ioNamePtr     pointer
  26370.   <->    22    ioVRefNum     word
  26371.   <->    24    ioRefNum      word
  26372.   -->    28    ioFCBIndx     long word
  26373.   <--    32    ioFCBFlNm     long word
  26374.   <--    36    ioFCBFlags    word
  26375.   <--    38    ioFCBStBlk    word
  26376.   <--    40    ioFCBEOF      long word
  26377.   <--    44    ioFCBPLen     long word
  26378.   <--    48    ioFCBCrPs     long word
  26379.   <--    52    ioFCBVRefNum  word
  26380.   <--    54    ioFCBClpSiz   long word
  26381.   <--    58    ioFCBParID    long word
  26382.  
  26383. PBGetFCBInfo returns information about the specified open file. If ioFCBIndx is
  26384. positive, the File Manager returns information about the file whose file number is
  26385. ioFCBIndx on the volume specified by ioVRefNum (which may contain a drive number,
  26386. volume reference number, or working directory reference number). If ioVRefNum is 0,
  26387. all open files are indexed; otherwise, only open files on the specified volume are
  26388. indexed.
  26389.  
  26390. If ioFCBIndx is 0, the File Manager returns information about the file whose access
  26391. path is specified by ioRefNum.
  26392.  
  26393. Assembly-language note:  The global variable FCBSPtr points to the
  26394.                          length word of the file-control-block buffer.
  26395.  
  26396. Each file control block contains 94 bytes of information about an access path; Figure
  26397. 28 shows its structure (using the assembly-language offsets).
  26398.  
  26399. •••Refer to Figure 28.•••
  26400.  
  26401. Figure 28–A File Control Block
  26402.  
  26403. 64K ROM note:  The structure of a file control block in the 64K ROM
  26404.                version of the File Manager is a subset of the above
  26405.                structure. The old file control block contained only
  26406.                the fields up to and including fcbFlPos.
  26407.  
  26408. FCBMdRByt (which corresponds to ioFCBFlags in the parameter block for PBGetFCBInfo)
  26409. contains flags that describe the status of the file, as follows:
  26410.  
  26411.   Bit    Meaning
  26412.   0     Set if data can be written to the file
  26413.   1     Set if the entry describes a resource fork
  26414.   7     Set if the file has been changed since it was last flushed
  26415.  
  26416. Warning:  The size and structure of a file control block may be
  26417.           different in future versions of Macintosh system software.
  26418.  
  26419. æKY PBGetCatInfo
  26420. æFc Files.h
  26421. æT Function
  26422. æD pascal OSErr PBGetCatInfo(CInfoPBPtr paramBlock,Boolean async); 
  26423. æDT OSErr myVariable = PBGetCatInfo((CInfoPBPtr) paramBlock,(Boolean) async);
  26424. æRT 68,69
  26425. æRI IV-155,  V-391, N68-1, N69, VI
  26426. æC
  26427. Some existing HFS functions now support file IDs as appropriate, but their
  26428. interface remains stable. This section describes how they accommodate file IDs.
  26429.  
  26430. FUNCTION PBGetCatInfo (paramBlock: HParamBlkPtr, async: Boolean) : OSErr;
  26431.  
  26432. You can use PBGetCatInfo to determine whether a file has a file ID.  The value
  26433. of the file ID is returned in ioDirID. Because that parameter could also
  26434. represent a directory ID, call PBResolveFileID to see if the value is a real
  26435. file ID.  If you want to both determine whether a file ID exists for a file and
  26436. create one if it doesn’t, use PBCreateFileID, which will either create a file ID
  26437. or return fidExists.
  26438.  
  26439. •••Refer to Technical Note #69:•••
  26440.  
  26441. Trap macro    _GetCatInfo
  26442.  
  26443. Parameter block
  26444.   Files:                                   Directories:
  26445.   -->    12    ioCompletion   pointer      -->    12    ioCompletion  pointer
  26446.   <--    16    ioResult       word         <--    16    ioResult      word
  26447.   <->    18    ioNamePtr      pointer      <->    18    ioNamePtr     pointer
  26448.   -->    22    ioVRefNum      word         -->    22    ioVRefNum     word
  26449.   <--    24    ioFRefNum      word         <--    24    ioFRefNum     word
  26450.   -->    28    ioFDirIndex    word         -->    28    ioFDirIndex   word
  26451.   <--    30    ioFlAttrib     byte         <--    30    ioFlAttrib    byte
  26452.   <--    31    ioACUser       byte         access rights for directory only
  26453.   <--    32    ioFlFndrInfo   16 bytes     <--    32    ioDrUsrWds    16 bytes
  26454.   <->    48    ioDirID        long word    <->    48    ioDrDirID     long word
  26455.   <--    52    ioFlStBlk      word         <--    52    ioDrNmFls     word
  26456.   <--    54    ioFlLgLen      long word
  26457.   <--    58    ioFlPyLen      long word
  26458.   <--    62    ioFlRStBlk     word
  26459.   <--    64    ioFlRLgLen     long word
  26460.   <--    68    ioFlRPyLen     long word
  26461.   <--    72    ioFlCrDat      long word    <--    72    ioDrCrDat    long word
  26462.   <--    76    ioFlMdDat      long word    <--    76    ioDrMdDat    long word
  26463.   <--    80    ioFlBkDat      long word    <--    80    ioDrBkDat    long word
  26464.   <--    84    ioFlXFndrInfo  16 bytes     <--    84    ioDrFndrInfo 16 bytes
  26465.   <--    100   ioFlParID      long word    <--    100    ioDrParID   long word
  26466.   <--    104   ioFlClpSiz     long word
  26467.  
  26468. PBGetCatInfo gets information about the files and directories in a file catalog. To
  26469. determine whether the information is for a file or a directory, test bit 4 of ioFlAttrib,
  26470. as described in the section “CInfoPBRec”. The information that’s returned for files
  26471. is shown in the left column, and the corresponding information for directories is
  26472. shown in the right column.
  26473.  
  26474. If ioFDirIndex is positive, the File Manager returns information about the file or
  26475. directory whose directory index is ioFDirIndex in the directory specified by ioVRefNum
  26476. (this will be the root directory if a volume reference number is provided).
  26477.  
  26478. If ioFDirIndex is 0, the File Manager returns information about the file or directory
  26479. specified by ioNamePtr, in the directory specified by ioVRefNum
  26480. (again, this will be the root directory if a volume reference number is provided).
  26481.  
  26482. If ioFDirIndex is negative, the File Manager ignores ioNamePtr and returns information
  26483. about the directory specified by ioDirID.
  26484.  
  26485. With files, PBGetCatInfo is similar to PBHGetFileInfo but returns some additional
  26486. information. If the file is open, the reference number of the first access path found
  26487. is returned in ioFRefNum, and the name of the file is returned in ioNamePtr (unless
  26488. ioNamePtr is NIL).
  26489.  
  26490. For server volume directories, in addition to the normal return parameters the ioACUser
  26491. field returns the user’s access rights in the following format:
  26492.  
  26493.   Bit    7    if set, user is not the owner of the directory.
  26494.               if clear, user is the owner of the directory.
  26495.          6–3  Reserved; this is returned set to zero.
  26496.          2    If set, user does not have Make Changes privileges
  26497.               to the directory.
  26498.               If clear, user has Make Changes privileges to the directory.
  26499.          1    If set, user does not have See Files privileges to the directory.
  26500.               If clear, user has See Files privileges to the directory.
  26501.          0    If set, user does not have See Folders privileges
  26502.               to the directory.
  26503.               If clear, user has See Folders privileges to the directory.
  26504.  
  26505. For example, if ioACUser returns zero for a given server volume directory, you know
  26506. that the user is the owner of the directory and has complete privileges to it.
  26507.  
  26508. Result codes    noErr     No error
  26509.                 bdNamErr  Bad file name
  26510.                 dirNFErr  Directory not found or incomplete pathname
  26511.                 extFSErr  External file system
  26512.                 fnfErr    File not found
  26513.                 ioErr     I/O error
  26514.                 nsvErr    No such volume
  26515.                 paramErr  No default volume
  26516.  
  26517. æKY PBSetCatInfo
  26518. æFc Files.h
  26519. æT Function
  26520. æD pascal OSErr PBSetCatInfo(CInfoPBPtr paramBlock,Boolean async); 
  26521. æDT OSErr myVariable = PBSetCatInfo((CInfoPBPtr) paramBlock,(Boolean) async);
  26522. æRI IV-156
  26523. æC 
  26524. Trap macro    _SetCatInfo
  26525.  
  26526. Parameter block
  26527.  
  26528.   Files:                                  Directories:
  26529.   -->    12    ioCompletion  pointer      -->    12    ioCompletion  pointer
  26530.   <--    16    ioResult      word         <--    16    ioResult      word
  26531.   <->    18    ioNamePtr     pointer      <->    18    ioNamePtr     pointer
  26532.   -->    22    ioVRefNum     word         -->    22    ioVRefNum     word
  26533.   -->    30    ioFlAttrib    byte         -->    30    ioFlAttrib    byte
  26534.   -->    32    ioFlFndrInfo  16 bytes     -->    32    ioDrUsrWds    16 bytes
  26535.   -->    48    ioDirID       long word    -->    48    ioDrDirID     long word
  26536.   -->    72    ioFlCrDat     long word    -->    72    ioDrCrDat     long word
  26537.   -->    76    ioFlMdDat     long word    -->    76    ioDrMdDat     long word
  26538.   -->    80    ioFlBkDat     long word    -->    80    ioDrBkDat     long word
  26539.   -->    84    ioFlXFndrInfo 16 bytes     -->    84    ioDrFndrInfo  16 bytes
  26540.   -->    104   ioFlClpSiz    long word
  26541.  
  26542. PBSetCatInfo sets information about the files and directories in a catalog. With
  26543. files, it’s similar to PBHSetFileInfo but lets you set some additional information.
  26544. The information that can be set for files is shown in the left column, and the corresponding
  26545. information for directories is shown in the right column.
  26546.  
  26547. Result codes    noErr     No error
  26548.                 bdNamErr  Bad file name
  26549.                 dirNFErr  Directory not found or incomplete pathname
  26550.                 extFSErr  External file system
  26551.                 fnfErr    File not found
  26552.                 ioErr     I/O error
  26553.                 nsvErr    No such volume
  26554.                 paramErr  No default volume
  26555.  
  26556. æKY PBAllocContig
  26557. æFc Files.h
  26558. æT Function
  26559. æD pascal OSErr PBAllocContig(ParmBlkPtr paramBlock,Boolean async); 
  26560. æDT OSErr myVariable = PBAllocContig((ParmBlkPtr) paramBlock,(Boolean) async);
  26561. æRI IV-143
  26562. æC 
  26563. Trap macro    _AllocContig
  26564.  
  26565. Parameter block
  26566.   -->    12    ioCompletion  pointer
  26567.   <--    16    ioResult      word
  26568.   -->    24    ioRefNum      word
  26569.   -->    36    ioReqCount    long word
  26570.   <--    40    ioActCount    long word
  26571.  
  26572. PBAllocContig is identical to PBAllocate except that if there isn’t enough contiguous
  26573. empty space on the volume to satisfy the allocation request, PBAllocContig will do
  26574. nothing and will return dskFulErr as its function result. If you want to allocate
  26575. whatever space is available, even when the entire request cannot be filled as a
  26576. contiguous piece, call PBAllocate instead.
  26577.  
  26578. Result codes    noErr      No error
  26579.                 dskFulErr  Disk full
  26580.                 fLckdErr   File locked
  26581.                 fnOpnErr   File not open
  26582.                 ioErr      I/O error
  26583.                 rfNumErr   Bad reference number
  26584.                 vLckdErr   Software volume lock
  26585.                 wPrErr     Hardware volume lock
  26586.                 wrPermErr  Read/write permission doesn’t allow writing
  26587.  
  26588. æKY PBLockRange
  26589. æFc Files.h
  26590. æT Function
  26591. æD pascal OSErr PBLockRange(ParmBlkPtr paramBlock,Boolean async); 
  26592. æDT OSErr myVariable = PBLockRange((ParmBlkPtr) paramBlock,(Boolean) async);
  26593. æRT 186
  26594. æRI IV-138
  26595. æC 
  26596. •••Refer to Technical Note #186:•••
  26597.  
  26598. Trap macro    _LockRng
  26599.  
  26600. Parameter block
  26601.   -->    12    ioCompletion  pointer
  26602.   <--    16    ioResult      word
  26603.   -->    24    ioRefNum      word
  26604.   -->    36    ioReqCount    long word
  26605.   -->    44    ioPosMode     word
  26606.   -->    46    ioPosOffset   long word
  26607.  
  26608. On a file opened with a shared read/write permission, PBLockRange is used in conjunction
  26609. with PBRead and PBWrite to lock a certain portion of the file. PBLockRange uses the
  26610. same parameters as both PBRead and PBWrite; by calling it immediately before PBRead,
  26611. you can use the information present in the parameter block for the PBRead call.
  26612.  
  26613. When you’re finished with the data (typically after a call to PBWrite), be sure to
  26614. call PBUnlockRange to free up that portion of the file for subsequent PBRead calls.
  26615.  
  26616. Warning:  PBLockRange operates only with the hierarchical version of the
  26617.           File Manager; if used on a Macintosh equipped only with the 64K
  26618.           ROM version of the File Manager, it will generate a system error.
  26619.  
  26620. Result codes    noErr     No error
  26621.                 eofErr    End-of-file
  26622.                 extFSErr  External file system
  26623.                 fnOpnErr  File not open
  26624.                 ioErr     I/O error
  26625.                 paramErr  Negative ioReqCount
  26626.                 rfNumErr  Bad reference number
  26627.  
  26628. æKY PBUnlockRange
  26629. æFc Files.h
  26630. æT Function
  26631. æD pascal OSErr PBUnlockRange(ParmBlkPtr paramBlock,Boolean async); 
  26632. æDT OSErr myVariable = PBUnlockRange((ParmBlkPtr) paramBlock,(Boolean) async);
  26633. æRT 186
  26634. æRI IV-139
  26635. æC 
  26636. Trap macro    _UnlockRng
  26637.  
  26638. Parameter block
  26639.   -->    12    ioCompletion  pointer
  26640.   <--    16    ioResult      word
  26641.   -->    24    ioRefNum      word
  26642.   -->    36    ioReqCount    long word
  26643.   -->    44    ioPosMode     word
  26644.   -->    46    ioPosOffset   long word
  26645.  
  26646. PBUnlockRange is used in conjunction with PBRead and PBWrite to unlock a certain
  26647. portion of a file that you locked with PBLockRange.
  26648.  
  26649. Warning:  PBUnlockRange operates only with the hierarchical version of
  26650.           the File Manager; if used on a Macintosh equipped only with
  26651.           the 64K ROM version of the File Manager, it will generate a
  26652.           system error.
  26653.  
  26654. Result codes    noErr     No error
  26655.                 eofErr    End-of-file
  26656.                 extFSErr  External file system
  26657.                 fnOpnErr  File not open
  26658.                 ioErr     I/O error
  26659.                 paramErr  Negative ioReqCount
  26660.                 rfNumErr  Bad reference number
  26661.  
  26662. æKY PBSetVInfo
  26663. æFc Files.h
  26664. æT Function
  26665. æD pascal OSErr PBSetVInfo(HParmBlkPtr paramBlock,Boolean async); 
  26666. æDT OSErr myVariable = PBSetVInfo((HParmBlkPtr) paramBlock,(Boolean) async);
  26667. æRT 204
  26668. æRI IV-131
  26669. æC 
  26670. •••Refer to Technical Note #204:•••
  26671.  
  26672. Trap macro    _SetVolInfo
  26673.  
  26674. Parameter block
  26675.   -->    12    ioCompletion  pointer
  26676.   <--    16    ioResult      word
  26677.   -->    18    ioNamePtr     pointer
  26678.   -->    22    ioVRefNum     word
  26679.   -->    30    ioVCrDate     long word
  26680.   -->    34    ioVLsMod      long word
  26681.   -->    38    ioVAtrb       word
  26682.   -->    52    ioVClpSiz     long word
  26683.   -->    72    ioVBkUp       long word
  26684.   -->    76    ioVSeqNum     word
  26685.   -->    90    ioVFndrInfo   32 bytes
  26686.  
  26687. PBSetVInfo lets you modify information about volumes. A pointer to a new name for the
  26688. volume can be specified in ioNamePtr. The date and time of the volume’s creation and
  26689. modification can be set with ioVCrDate and ioVLsMod respectively. Only bit 15 of
  26690. ioVAtrb can be changed; setting it locks the volume.
  26691.  
  26692. Note:  The volume cannot be specified by name; you must use either the
  26693.        volume reference number or the drive number.
  26694.  
  26695. Warning:  PBSetVInfo operates only with the hierarchical version of the
  26696.           File Manager; if used on a Macintosh equipped only with the
  26697.           64K ROM version of the File Manager, it will generate a system error.
  26698.  
  26699. Result codes    noErr       No error
  26700.                 nsvErr      No such volume
  26701.                 paramErr    No default volume
  26702.  
  26703. æKY PBHGetVInfo
  26704. æFc Files.h
  26705. æT Function
  26706. æD pascal OSErr PBHGetVInfo(HParmBlkPtr paramBlock,Boolean async); 
  26707. æDT OSErr myVariable = PBHGetVInfo((HParmBlkPtr) paramBlock,(Boolean) async);
  26708. æRT 24, 66, 67, 77, 106, 157
  26709. æRI IV-130, N66-1, N67-1, N77-5  
  26710. æC 
  26711. Trap macro    _HGetVInfo
  26712.  
  26713. Parameter block
  26714.   -->    12    ioCompletion  pointer
  26715.   <--    16    ioResult      word
  26716.   <->    18    ioNamePtr     pointer
  26717.   <->    22    ioVRefNum     word
  26718.   -->    28    ioVolIndex    word
  26719.   <--    30    ioVCrDate     long word
  26720.   <--    34    ioVLsMod      long word
  26721.   <--    38    ioVAtrb       word
  26722.   <--    40    ioVNmFls      word
  26723.   <--    42    ioVBitMap     word
  26724.   <--    44    ioVAllocPtr   word
  26725.   <--    46    ioVNmAlBlks   word
  26726.   <--    48    ioVAlBlkSiz   long word
  26727.   <--    52    ioVClpSiz     long word
  26728.   <--    56    ioAlBlSt      word
  26729.   <--    58    ioVNxtFNum    long word
  26730.   <--    62    ioVFrBlk      word
  26731.   <--    64    ioVSigWord    word
  26732.   <--    66    ioVDrvInfo    word
  26733.   <--    68    ioVDRefNum    word
  26734.   <--    70    ioVFSID       word
  26735.   <--    72    ioVBkUp       long word
  26736.   <--    76    ioVSeqNum     word
  26737.   <--    78    ioVWrCnt      long word
  26738.   <--    82    ioVFilCnt     long word
  26739.   <--    86    ioVDirCnt     long word
  26740.   <--    90    ioVFndrInfo   32 bytes
  26741.  
  26742. PBHGetVInfo is similar in function to PBGetVInfo but returns a larger parameter
  26743. block. In addition, PBHGetVInfo always returns the volume reference number in ioVRefNum
  26744. (regardless of what was passed in). Also, ioVNmAlBlks and ioVFrBlks are not clipped
  26745. as they are by PBGetVInfo.
  26746.  
  26747. Result codes    noErr       No error
  26748.                 nsvErr      No such volume
  26749.                 paramErr    No default volume
  26750.  
  26751. æKY PBHOpen
  26752. æFc Files.h
  26753. æT Function
  26754. æD pascal OSErr PBHOpen(HParmBlkPtr paramBlock,Boolean async); 
  26755. æDT OSErr myVariable = PBHOpen((HParmBlkPtr) paramBlock,(Boolean) async);
  26756. æRT 204
  26757. æRI IV-136 
  26758. æC 
  26759. Trap macro    _HOpen
  26760.  
  26761. Parameter block
  26762.   -->    12    ioCompletion  pointer
  26763.   <--    16    ioResult      word
  26764.   -->    18    ioNamePtr     pointer
  26765.   -->    22    ioVRefNum     word
  26766.   <--    24    ioRefNum      word
  26767.   -->    27    ioPermssn     byte
  26768.   -->    28    ioMisc        pointer
  26769.   -->    48    ioDirID       long word
  26770.  
  26771. PBHOpen is identical to PBOpen except that it accepts a directory ID in ioDirID.
  26772.  
  26773. Result codes    noErr     No error
  26774.                 bdNamErr  Bad file name
  26775.                 dirNFErr  Directory not found or incomplete pathname
  26776.                 extFSErr  External file system
  26777.                 fnfErr    File not found
  26778.                 ioErr     I/O error
  26779.                 nsvErr    No such volume
  26780.                 opWrErr   File already open for writing
  26781.                 permErr   Attempt to open locked file for writing
  26782.                 tmfoErr   Too many files open
  26783.  
  26784. æKY PBHOpenRF
  26785. æFc Files.h
  26786. æT Function
  26787. æD pascal OSErr PBHOpenRF(HParmBlkPtr paramBlock,Boolean async); 
  26788. æDT OSErr myVariable = PBHOpenRF((HParmBlkPtr) paramBlock,(Boolean) async);
  26789. æRI IV-137
  26790. æC 
  26791. Trap macro    _HOpenRF
  26792.  
  26793. Parameter block
  26794.   -->    12    ioCompletion  pointer
  26795.   <--    16    ioResult      word
  26796.   -->    18    ioNamePtr     pointer
  26797.   -->    22    ioVRefNum     word
  26798.   <--    24    ioRefNum      word
  26799.   -->    27    ioPermssn     byte
  26800.   -->    28    ioMisc        pointer
  26801.   -->    48    ioDirID       long word
  26802.  
  26803. PBHOpenRF is identical to PBOpenRF except that it accepts a directory ID in ioDirID.
  26804.  
  26805. Result codes    noErr     No error
  26806.                 bdNamErr  Bad file name
  26807.                 dirNFErr  Directory not found or incomplete pathname
  26808.                 extFSErr  External file system
  26809.                 fnfErr    File not found
  26810.                 ioErr     I/O error
  26811.                 nsvErr    No such volume
  26812.                 opWrErr   File already open for writing
  26813.                 permErr   Attempt to open locked file for writing
  26814.                 tmfoErr   Too many files open
  26815.  
  26816. æKY PBHOpenDF
  26817. æFc Files.h
  26818. æT Function
  26819. æD pascal OSErr PBHOpenDF(HParmBlkPtr paramBlock,Boolean async); 
  26820. æDT OSErr myVariable = PBHOpenDF((HParmBlkPtr) paramBlock,(Boolean) async);
  26821. æRI VI
  26822. æC 
  26823. PBHOpenDF creates an access path to the data fork of a file. It is an HFS
  26824. version of PBOpenDF.
  26825.  
  26826. æKY PBHCreate
  26827. æFc Files.h
  26828. æT Function
  26829. æD pascal OSErr PBHCreate(HParmBlkPtr paramBlock,Boolean async); 
  26830. æDT OSErr myVariable = PBHCreate((HParmBlkPtr) paramBlock,(Boolean) async);
  26831. æRI IV-146 
  26832. æC 
  26833. Trap macro    _HCreate
  26834.  
  26835. Parameter block
  26836.   -->    12    ioCompletion  pointer
  26837.   <--    16    ioResult      word
  26838.   -->    18    ioNamePtr     pointer
  26839.   -->    22    ioVRefNum     word
  26840.   -->    48    ioDirID       long word
  26841.  
  26842. PBHCreate is identical to PBCreate except that it accepts a directory ID in ioDirID.
  26843.  
  26844. Note:  To create a directory instead of a file, call PBDirCreate.
  26845.  
  26846. Result codes    noErr      No error
  26847.                 bdNamErr   Bad file name
  26848.                 dupFNErr   Duplicate file name and version
  26849.                 dirFulErr  File directory full
  26850.                 dirNFErr   Directory not found or incomplete pathname
  26851.                 extFSErr   External file system
  26852.                 ioErr      I/O error
  26853.                 nsvErr     No such volume
  26854.                 vLckdErr   Software volume lock
  26855.                 wPrErr     Hardware volume lock
  26856.  
  26857. æKY PBHDelete
  26858. æFc Files.h
  26859. æT Function
  26860. æD pascal OSErr PBHDelete(HParmBlkPtr paramBlock,Boolean async); 
  26861. æDT OSErr myVariable = PBHDelete((HParmBlkPtr) paramBlock,(Boolean) async);
  26862. æRI IV-147, VI
  26863. æC 
  26864. Some existing HFS functions now support file IDs as appropriate, but their
  26865. interface remains stable. This section describes how they accommodate file IDs.
  26866.  
  26867. FUNCTION PBHDelete (paramBlock: HParamBlkPtr, async: Boolean) : OSErr;
  26868.  
  26869. If a file ID exists for the file being deleted, the file ID is also deleted.
  26870.  
  26871.  
  26872. Trap macro    _HDelete
  26873.  
  26874. Parameter block
  26875.   -->    12    ioCompletion  pointer
  26876.   <--    16    ioResult      word
  26877.   -->    18    ioNamePtr     pointer
  26878.   -->    22    ioVRefNum     word
  26879.   -->    48    ioDirID       long word
  26880.  
  26881. PBHDelete is identical to PBDelete except that it accepts a directory ID in ioDirID.
  26882. PBHDelete can be used to delete an empty directory as well.
  26883.  
  26884. Result codes    noErr     No error
  26885.                 bdNamErr  Bad file name
  26886.                 dirNFErr  Directory not found or incomplete pathname
  26887.                 extFSErr  External file system
  26888.                 fBsyErr   File busy, directory not empty, or working
  26889.                           directory control block open
  26890.                 fLckdErr  File locked
  26891.                 fnfErr    File not found
  26892.                 nsvErr    No such volume
  26893.                 ioErr     I/O error
  26894.                 vLckdErr  Software volume lock
  26895.                 wPrErr    Hardware volume lock
  26896.  
  26897. æKY PBHRename
  26898. æFc Files.h
  26899. æT Function
  26900. æD pascal OSErr PBHRename(HParmBlkPtr paramBlock,Boolean async); 
  26901. æDT OSErr myVariable = PBHRename((HParmBlkPtr) paramBlock,(Boolean) async);
  26902. æRI IV-154, VI 
  26903. æC 
  26904.  
  26905.  
  26906. Some existing HFS functions now support file IDs as appropriate, but their
  26907. interface remains stable. This section describes how they accommodate file IDs.
  26908.  
  26909.  
  26910. FUNCTION PBHRename (paramBlock: HParamBlkPtr, async: Boolean) : OSErr;
  26911.  
  26912. If a file ID exists for the file being renamed, the file ID remains with the
  26913. file.
  26914.  
  26915. Trap macro    _HRename
  26916.  
  26917. Parameter block
  26918.   -->    12    ioCompletion  pointer
  26919.   <--    16    ioResult      word
  26920.   -->    18    ioNamePtr     pointer
  26921.   -->    22    ioVRefNum     word
  26922.   -->    28    ioMisc        pointer
  26923.   -->    48    ioDirID       long word
  26924.  
  26925. PBHRename is identical to PBRename except that it accepts a directory ID in ioDirID
  26926. and can be used to rename directories as well as files and volumes. Given a pointer
  26927. to the name of a file or directory in ioNamePtr, PBHRename changes it to the name
  26928. pointed to by ioMisc. Given a pointer to a volume name in ioNamePtr or a volume
  26929. reference number in ioVRefNum, it changes the name of the volume to the name pointed
  26930. to by ioMisc.
  26931.  
  26932. Warning:  PBHRename cannot be used to change the directory a file is in.
  26933.  
  26934. Result codes    noErr      No error
  26935.                 bdNamErr   Bad file name
  26936.                 dirFulErr  File directory full
  26937.                 dirNFErr   Directory not found or incomplete pathname
  26938.                 dupFNErr   Duplicate file name and version
  26939.                 extFSErr   External file system
  26940.                 fLckdErr   File locked
  26941.                 fnfErr     File not found
  26942.                 fsRnErr    Problem during rename
  26943.                 ioErr      I/O error
  26944.                 nsvErr     No such volume
  26945.                 paramErr   No default volume
  26946.                 vLckdErr   Software volume lock
  26947.                 wPrErr     Hardware volume lock
  26948.  
  26949. æKY PBHRstFLock
  26950. æFc Files.h
  26951. æT Function
  26952. æD pascal OSErr PBHRstFLock(HParmBlkPtr paramBlock,Boolean async); 
  26953. æDT OSErr myVariable = PBHRstFLock((HParmBlkPtr) paramBlock,(Boolean) async);
  26954. æRI IV-152 
  26955. æC 
  26956. Trap macro    _HRstFLock
  26957.  
  26958. Parameter block
  26959.   -->    12    ioCompletion  pointer
  26960.   <--    16    ioResult      word
  26961.   -->    18    ioNamePtr     pointer
  26962.   -->    22    ioVRefNum     word
  26963.   -->    48    ioDirID       long word
  26964.  
  26965. PBHRstFLock is identical to PBRstFLock except that it accepts a directory ID in
  26966. ioDirID.
  26967.  
  26968. Result codes    noErr     No error
  26969.                 dirNFErr  Directory not found or incomplete pathname
  26970.                 extFSErr  External file system
  26971.                 fnfErr    File not found
  26972.                 ioErr     I/O error
  26973.                 nsvErr    No such volume
  26974.                 vLckdErr  Software volume lock
  26975.                 wPrErr    Hardware volume lock
  26976.  
  26977. æKY PBHSetFLock
  26978. æFc Files.h
  26979. æT Function
  26980. æD pascal OSErr PBHSetFLock(HParmBlkPtr paramBlock,Boolean async); 
  26981. æDT OSErr myVariable = PBHSetFLock((HParmBlkPtr) paramBlock,(Boolean) async);
  26982. æRI IV-151
  26983. æC 
  26984. Trap macro    _HSetFLock
  26985.  
  26986. Parameter block
  26987.   -->    12    ioCompletion  pointer
  26988.   <--    16    ioResult      word
  26989.   -->    18    ioNamePtr     pointer
  26990.   -->    22    ioVRefNum     word
  26991.   -->    48    ioDirID       long word
  26992.  
  26993. PBHSetFLock is identical to PBSetFLock except that it accepts a directory ID in
  26994. ioDirID.
  26995.  
  26996. Result codes    noErr     No error
  26997.                 dirNFErr  Directory not found or incomplete pathname
  26998.                 extFSErr  External file system
  26999.                 fnfErr    File not found
  27000.                 ioErr     I/O error
  27001.                 nsvErr    No such volume
  27002.                 vLckdErr  Software volume lock
  27003.                 wPrErr    Hardware volume lock
  27004.  
  27005. æKY PBHGetFInfo
  27006. æFc Files.h
  27007. æT Function
  27008. æD pascal OSErr PBHGetFInfo(HParmBlkPtr paramBlock,Boolean async); 
  27009. æDT OSErr myVariable = PBHGetFInfo((HParmBlkPtr) paramBlock,(Boolean) async);
  27010. æRI IV-149 
  27011. æC 
  27012. Trap macro    _HGetFileInfo
  27013.  
  27014. Parameter block
  27015.   -->    12    ioCompletion  pointer
  27016.   <--    16    ioResult      word
  27017.   <->    18    ioNamePtr     pointer
  27018.   -->    22    ioVRefNum     word
  27019.   <--    24    ioFRefNum     word
  27020.   -->    28    ioFDirIndex   word
  27021.   <--    30    ioFlAttrib    byte
  27022.   <--    32    ioFlFndrInfo  16 bytes
  27023.   <->    48    ioDirID       long word
  27024.   <--    52    ioFlStBlk     word
  27025.   <--    54    ioFlLgLen     long word
  27026.   <--    58    ioFlPyLen     long word
  27027.   <--    62    ioFlRStBlk    word
  27028.   <--    64    ioFlRLgLen    long word
  27029.   <--    68    ioFlRPyLen    long word
  27030.   <--    72    ioFlCrDat     long word
  27031.   <--    76    ioFlMdDat     long word
  27032.  
  27033. PBHGetFInfo is identical to PBGetFInfo except that it accepts a directory ID in
  27034. ioDirID.
  27035.  
  27036. Result codes    noErr     No error
  27037.                 bdNamErr  Bad file name
  27038.                 dirNFErr  Directory not found or incomplete pathname
  27039.                 extFSErr  External file system
  27040.                 fnfErr    File not found
  27041.                 ioErr     I/O error
  27042.                 nsvErr    No such volume
  27043.                 paramErr  No default volume
  27044.  
  27045. æKY PBHSetFInfo
  27046. æFc Files.h
  27047. æT Function
  27048. æD pascal OSErr PBHSetFInfo(HParmBlkPtr paramBlock,Boolean async); 
  27049. æDT OSErr myVariable = PBHSetFInfo((HParmBlkPtr) paramBlock,(Boolean) async);
  27050. æRI IV-150
  27051. æC 
  27052. Trap macro    _HSetFileInfo
  27053.  
  27054. Parameter block
  27055.   -->    12    ioCompletion  pointer
  27056.   <--    16    ioResult      word
  27057.   -->    18    ioNamePtr     pointer
  27058.   -->    22    ioVRefNum     word
  27059.   -->    32    ioFlFndrInfo  16 bytes
  27060.   -->    48    ioDirID       long word
  27061.   -->    72    ioFlCrDat     long word
  27062.   -->    76    ioFlMdDat     long word
  27063.  
  27064. PBHSetFInfo is identical to PBSetFInfo except that it accepts a directory ID in
  27065. ioDirID.
  27066.  
  27067. Result codes    noErr     No error
  27068.                 bdNamErr  Bad file name
  27069.                 dirNFErr  Directory not found or incomplete pathname
  27070.                 extFSErr  External file system
  27071.                 fLckdErr  File locked
  27072.                 fnfErr    File not found
  27073.                 ioErr     I/O error
  27074.                 nsvErr    No such volume
  27075.                 vLckdErr  Software volume lock
  27076.                 wPrErr    Hardware volume lock
  27077.  
  27078. æKY PBGetAltAccess
  27079. æFc Files.h
  27080. æT Function
  27081. æD pascal OSErr PBGetAltAccess(HParmBlkPtr paramBlock,Boolean async); 
  27082. æDT OSErr myVariable = PBGetAltAccess((HParmBlkPtr) paramBlock,(Boolean) async);
  27083. æRI VI
  27084. æC 
  27085. Parameter block
  27086.   Æ   12  ioCompletion   long  pointer to completion routine
  27087.   ¨   16  ioResult       word  result code
  27088.   Æ   18  ioNamePtr      long  pointer to volume name
  27089.   ¨   22  ioVRefNum      word  volume reference number
  27090.   ¨   32  ioBuffer       long  pointer to privilege info buffer
  27091.   Æ   36  ioReqCount     long  size allocated for buffer
  27092.   ¨   40  ioActCount     long  amount used in buffer
  27093.   ¨   44  ioAccessInfo1  long  information specific to privilege model
  27094.   ¨   48  ioAccessInfo2  long  information specific to privilege model
  27095.   ¨   52  ioAccessInfo3  long  information specific to privilege model
  27096.   ¨   56  ioAccessInfo4  long  information specific to privilege model
  27097.   Æ   60  ioDirID        word  parent directory ID
  27098.  
  27099. PBGetAltAccess retrieves access information from a volume managed by a file
  27100. system that uses a privilege model different from the AFP model.
  27101.  
  27102. Result codes
  27103. <to come>
  27104.  
  27105. æKY PBSetAltAccess
  27106. æFc Files.h
  27107. æT Function
  27108. æD pascal OSErr PBSetAltAccess(HParmBlkPtr paramBlock,Boolean async); 
  27109. æDT OSErr myVariable = PBSetAltAccess((HParmBlkPtr) paramBlock,(Boolean) async);
  27110. æRI VI
  27111. æC 
  27112. Parameter block
  27113.   Æ   12  ioCompletion   long  pointer to completion routine
  27114.   ¨   16  ioResult       word  result code
  27115.   Æ   18  ioNamePtr      long  pointer to volume name
  27116.   Æ   22  ioVRefNum      word  volume reference number
  27117.   ¨   32  ioBuffer       long  pointer to privilege info buffer
  27118.   Æ   36  ioReqCount     long  size allocated for buffer
  27119.   ¨   40  ioActCount     long  amount used in buffer
  27120.   Æ   44  ioAccessInfo1  long  information specific to privilege model
  27121.   Æ   48  ioAccessInfo2  long  information specific to privilege model
  27122.   Æ   52  ioAccessInfo3  long  information specific to privilege model
  27123.   Æ   56  ioAccessInfo4  long  information specific to privilege model
  27124.   Æ   60  ioDirID        word  parent directory ID
  27125.  
  27126. PBSetAltAccess modifies access information from a volume managed by a file
  27127. system that uses a privilege model different from the AFP model.
  27128.  
  27129. Result codes
  27130. <to come>
  27131.  
  27132. æKY PBMakeFSSpec
  27133. æFc Files.h
  27134. æT Function
  27135. æD 
  27136. pascal OSErr PBMakeFSSpec(HParamBlkPtr paramBlock,Boolean async); 
  27137. æDT OSErr myVariable = PBMakeFSSpec((HParamBlkPtr) paramBlock,(Boolean) async);
  27138. æC 
  27139.  
  27140. æKY FInitQueue
  27141. æFc Files.h
  27142. æT Function
  27143. æTN A016
  27144. æD pascal void FInitQueue(void)
  27145.     = 0xA016; 
  27146. æDT FInitQueue()(void);
  27147. æRI II-103, IV-128
  27148. æC 
  27149. Trap macro    _InitQueue
  27150.  
  27151. FInitQueue clears all queued File Manager calls except the current one.
  27152.  
  27153. æKY GetFSQHdr
  27154. æFc Files.h
  27155. æT Function
  27156. æD pascal QHdrPtr GetFSQHdr(void); 
  27157. æDT QHdrPtr myVariable = GetFSQHdr()(void);
  27158. æRI II-125, IV-175
  27159. æC 
  27160. You can get a pointer to the header of the file I/O queue by calling the File Manager
  27161. function GetFSQHdr.
  27162.  
  27163. FUNCTION GetFSQHdr :  QHdrPtr; [Not in ROM]
  27164.  
  27165. GetFSQHdr returns a pointer to the header of the file I/O queue.
  27166.  
  27167. Assembly-language note:  The global variable FSQHdr contains the
  27168.                          header of the file I/O queue.
  27169.  
  27170. æKY GetDrvQHdr
  27171. æFc Files.h
  27172. æT Function
  27173. æD pascal QHdrPtr GetDrvQHdr(void); 
  27174. æDT QHdrPtr myVariable = GetDrvQHdr()(void);
  27175. æRI II-128, IV-181
  27176. æC 
  27177. You can get a pointer to the header of the drive queue by calling the File Manager
  27178. function GetDrvQHdr.
  27179.  
  27180. FUNCTION GetDrvQHdr :  QHdrPtr; [Not in ROM]
  27181.  
  27182. GetDrvQHdr returns a pointer to the header of the drive queue.
  27183.  
  27184. Assembly-language note:  The global variable DrvQHdr contains the
  27185.                          header of the drive queue.
  27186.  
  27187. The drive queue can support any number of drives, limited only by memory space.
  27188.  
  27189. æKY GetVCBQHdr
  27190. æFc Files.h
  27191. æT Function
  27192. æD pascal QHdrPtr GetVCBQHdr(void); 
  27193. æDT QHdrPtr myVariable = GetVCBQHdr()(void);
  27194. æRI II-126, IV-178
  27195. æC 
  27196. You can get a pointer to the header of the volume-control-block queue by calling the
  27197. File Manager function GetVCBQHdr.
  27198.  
  27199. FUNCTION GetVCBQHdr :  QHdrPtr; [Not in ROM]
  27200.  
  27201. GetVCBQHdr returns a pointer to the header of the volume-control-block queue.
  27202.  
  27203. Assembly-language note:  The global variable VCBQHdr contains the header
  27204.                          of the volume-control-block-queue. The default
  27205.                          volume’s volume control block is pointed to by
  27206.                          the global variable DefVCBPtr.
  27207.  
  27208. æKY HGetVol
  27209. æFc Files.h
  27210. æT Function
  27211. æD pascal OSErr HGetVol(StringPtr volName,short *vRefNum,long *dirID); 
  27212. æDT OSErr myVariable = HGetVol((StringPtr) volName,(short *) vRefNum,(long *) dirID);
  27213. æRI IV-132, VI
  27214. æC 
  27215. HGetVol  is an HFS version of the MFS function GetVol. It calls the function
  27216. PBHGetVol, documented in the File Manager chapter of Volume IV. vRefNum can hold
  27217. a volume reference number or a working directory reference number. dirID holds a
  27218. directory ID.
  27219.  
  27220. Trap macro  _HGetVol
  27221.  
  27222. Parameter block
  27223.   —>  12  ioCompletion  pointer
  27224.   <—  16  ioResult        word
  27225.   <—  18  ioNamePtr       pointer
  27226.   <—  22  ioVRefNum       word
  27227.   <—  28  ioWDProcID       long word
  27228.   <—  32  ioWDVRefNum  word
  27229.   <—  48  ioWDDirID  long word  
  27230.  
  27231. PBHGetVol returns the default volume and directory last set by either a 
  27232. PBSetVol or a PBHSetVol call.  The reference number of the default volume 
  27233. is returned in ioVRefNum.
  27234.  
  27235. Warning:
  27236.  
  27237.     IOVRefNum will return a working directory reference 
  27238.     number (instead of the volume reference number) if, in the last call to 
  27239.     PBSetVol or PBHSetVol, a working directory reference number was 
  27240.     passed in this field.  
  27241.  
  27242. The volume reference number of the volume on which the default directory 
  27243. exists is returned in ioWDVRefNum.  The directory ID of the default 
  27244. directory is returned in ioWDDirID.
  27245.  
  27246. Result codes
  27247.  
  27248.     noErr  No error
  27249.     nsvErr  No default volume
  27250.  
  27251. æKY HSetVol
  27252. æFc Files.h
  27253. æT Function
  27254. æD pascal OSErr HSetVol(StringPtr volName,short vRefNum,long dirID); 
  27255. æDT OSErr myVariable = HSetVol((StringPtr) volName,(short) vRefNum,(long) dirID);
  27256. æRI IV-133, VI
  27257. æC 
  27258. HSetVol is an HFS version of the MFS function GetVol. It calls the function
  27259. PBHGetVol, documented in the File Manager chapter of Volume IV. vRefNum can hold
  27260. a volume reference number or a working directory reference number. dirID holds a
  27261. directory ID.
  27262.  
  27263. <Note: Don’t use HSetVol or PBHSetVol.>
  27264.  
  27265.  
  27266. æKY HOpen
  27267. æFc Files.h
  27268. æT Function
  27269. æD pascal OSErr HOpen(short vRefNum,long dirID,const Str255 fileName,char permission,
  27270.     short *refNum); 
  27271. æDT OSErr myVariable = HOpen((short) vRefNum,(long) dirID,(const Str255) fileName,(char) permission,(
  27272.     short) * refNum);
  27273. æRI IV-136, VI
  27274. æC 
  27275. HOpen creates an access path to the data fork of a file. It is an HFS version of
  27276. the MFS function Open. It calls the function PBHOpen, documented in the File
  27277. Manager chapter of Volume IV.
  27278.  
  27279. Trap macro  _HOpen
  27280.  
  27281. Parameter block
  27282.   —>  12  ioCompletion  pointer
  27283.   <—  16  ioResult  word
  27284.   —>  18  ioNamePtr  pointer
  27285.   —>  22  ioVRefNum  word
  27286.   <—  24  ioRefNum  word
  27287.   —>  27  ioPermssn  byte
  27288.   —>  28  ioMisc  pointer
  27289.   —>  48  ioDirID  long word
  27290.  
  27291. PBHOpen is identical to PBOpen except that it accepts a directory ID in 
  27292. ioDirID.
  27293.  
  27294. Result codes
  27295.   
  27296.   noErr     No error
  27297.   bdNamErr  Bad file name
  27298.   dirNFErr  Directory not found or incomplete pathname
  27299.   extFSErr  External file system
  27300.   fnfErr    File not found
  27301.   ioErr     I/O error
  27302.   nsvErr    No such volume
  27303.   opWrErr   File already open for writing
  27304.   permErr   Attempt to open locked file for writing
  27305.   tmfoErr   Too many files open
  27306.  
  27307. æKY HOpenRF
  27308. æFc Files.h
  27309. æT Function
  27310. æD pascal OSErr HOpenRF(short vRefNum,long dirID,const Str255 fileName,char permission,
  27311.     short *refNum); 
  27312. æDT OSErr myVariable = HOpenRF((short) vRefNum,(long) dirID,(const Str255) fileName,(char) permission,(
  27313.     short) * refNum);
  27314. æRI IV-137, VI
  27315. æC 
  27316. HOpenRF creates an access path to the resource fork of a file. It is an HFS
  27317. version of the MFS function OpenRF. It calls the function PBHOpenRF, documented
  27318. in the File Manager chapter of Volume IV.
  27319.  
  27320. Trap macro  _HOpenRF
  27321.  
  27322. Parameter block
  27323.     —>  12  ioCompletion    pointer
  27324.     <—  16  ioResult        word
  27325.     —>  18  ioNamePtr       pointer
  27326.     —>  22  ioVRefNum       word
  27327.     <—  24  ioRefNum        word
  27328.     —>  27  ioPermssn       byte
  27329.     —>  28  ioMisc          pointer
  27330.     —>  48  ioDirID         long word
  27331.  
  27332.     PBHOpenRF is identical to PBOpenRF except that it accepts a
  27333. directory ID in ioDirID.
  27334.  
  27335. Result codes
  27336.  
  27337.     noErr       No error
  27338.     bdNamErr    Bad file name
  27339.     dirNFErr    Directory not found or incomplete pathname
  27340.     extFSErr    External file system
  27341.     fnfErr      File not found
  27342.     ioErr       I/O error
  27343.     nsvErr      No such volume
  27344.     opWrErr     File already open for writing
  27345.     permErr     Attempt to open locked file for writing
  27346.     tmfoErr     Too many files open
  27347.  
  27348. æKY AllocContig
  27349. æFc Files.h
  27350. æT Function
  27351. æD pascal OSErr AllocContig(short refNum,long *count); 
  27352. æDT OSErr myVariable = AllocContig((short) refNum,(long *) count);
  27353. æRT 218
  27354. æRI IV-143, VI
  27355. æC 
  27356. AllocContig is a high-level function that calls PBAllocContig.
  27357.  
  27358. Trap macro  _AllocContig
  27359.  
  27360. Parameter block
  27361.     —>  12  ioCompletion    pointer
  27362.     <—  16  ioResult        word
  27363.     —>  24  ioRefNum        word
  27364.     —>  36  ioReqCount      long word
  27365.     <—  40  ioActCount      long word
  27366.  
  27367.     PBAllocContig is identical to PBAllocate except that if there isn’t
  27368. enough contiguous empty space on the volume to satisfy the allocation
  27369. request, PBAllocContig will do nothing and will return dskFulErr as its
  27370. function result. If you want to allocate whatever space is available,
  27371. even when the entire request cannot be filled as a contiguous piece,
  27372. call PBAllocate instead.
  27373.  
  27374. Result codes
  27375.  
  27376.     noErr       No error
  27377.     dskFulErr   Disk full
  27378.     fLckdErr    File locked
  27379.     fnOpnErr    File not open
  27380.     ioErr       I/O error
  27381.     rfNumErr    Bad reference number
  27382.     vLckdErr    Software volume lock
  27383.     wPrErr      Hardware volume lock
  27384.     wrPermErr   Read/write permission doesn’t allow writing
  27385.  
  27386. æKY HCreate
  27387. æFc Files.h
  27388. æT Function
  27389. æD pascal OSErr HCreate(short vRefNum,long dirID,const Str255 fileName,OSType creator,
  27390.     OSType fileType); 
  27391. æDT OSErr myVariable = HCreate((short) vRefNum,(long) dirID,(const Str255) fileName,(OSType) creator,()
  27392.     OSType fileType);
  27393. æRT 218
  27394. æRI IV-146, VI
  27395. æC 
  27396. HCreate creates a new file and sets the type and creator. It is an HFS version
  27397. of the MFS function Create.  vRefNum can hold a volume reference number or a
  27398. working directory reference number. dirID holds a directory ID.
  27399.  
  27400. HCreate calls the function PBHCreate, documented in the File Manager chapter of
  27401. Volume IV.
  27402.  
  27403. Trap macro  _HCreate
  27404.  
  27405. Parameter block
  27406.     —>  12  ioCompletion    pointer
  27407.     <—  16  ioResult        word
  27408.     —>  18  ioNamePtr       pointer
  27409.     —>  22  ioVRefNum       word
  27410.     —>  48  ioDirID         long word
  27411.  
  27412.     PBHCreate is identical to PBCreate except that it accepts a
  27413. directory ID in ioDirID.
  27414.  
  27415. Note:  
  27416.  
  27417.     To create a directory instead of a file, call PBDirCreate.
  27418.  
  27419. Result codes
  27420.  
  27421.     noErr       No error
  27422.     bdNamErr    Bad file name
  27423.     dupFNErr    Duplicate file name and version
  27424.     dirFulErr   File directory full
  27425.     dirNFErr    Directory not found or incomplete pathname
  27426.     extFSErr    External file system
  27427.     ioErr       I/O error
  27428.     nsvErr      No such volume
  27429.     vLckdErr    Software volume lock
  27430.     wPrErr      Hardware volume lock
  27431.  
  27432. æKY DirCreate
  27433. æFc Files.h
  27434. æT Function
  27435. æD pascal OSErr DirCreate(short vRefNum,long parentDirID,const Str255 directoryName,
  27436.     long *createdDirID); 
  27437. æDT OSErr myVariable = DirCreate((short) vRefNum,(long) parentDirID,(const Str255) directoryName,(
  27438.     long) * createdDirID);
  27439. æRT 218
  27440. æRI IV-146, VI
  27441. æC 
  27442. DirCreate is a high-level function that calls PBDirCreate.
  27443.  
  27444. Trap macro  _DirCreate
  27445.  
  27446. Parameter block
  27447.     —>  12  ioCompletion    pointer
  27448.     <—  16  ioResult        word
  27449.     <–> 18  ioNamePtr       pointer
  27450.     —>  22  ioVRefNum       word
  27451.     <–> 48  ioDirID         long word
  27452.  
  27453.     PBDirCreate is identical to PBHCreate except that it creates a new
  27454. directory instead of a file. You can specify the parent of the
  27455. directory to be created in ioDirID; if it’s 0, the new directory will be
  27456. placed in the root directory. The directory ID of the new directory is
  27457. returned in ioDirID.
  27458.  
  27459. Warning:
  27460.  
  27461.     PBDirCreate operates only with the hierarchical version of the
  27462.     File Manager; if used on a Macintosh equipped only with the
  27463.     64K ROM version of the File Manager, it will generate a system
  27464.     error.
  27465.  
  27466. Result codes
  27467.  
  27468.     noErr       No error
  27469.     bdNamErr    Bad file name
  27470.     dupFNErr    Duplicate file name and version
  27471.     dirFulErr   File directory full
  27472.     dirNFErr    Directory not found or incomplete pathname
  27473.     extFSErr    External file system
  27474.     ioErr       I/O error
  27475.     nsvErr      No such volume
  27476.     vLckdErr    Software volume lock
  27477.     wPrErr      Hardware volume lock
  27478.  
  27479. æKY HDelete
  27480. æFc Files.h
  27481. æT Function
  27482. æD pascal OSErr HDelete(short vRefNum,long dirID,const Str255 fileName); 
  27483. æDT OSErr myVariable = HDelete((short) vRefNum,(long) dirID,(const Str255) fileName);
  27484. æRI IV-147, VI
  27485. æC 
  27486. HDelete removes a closed file. It is an HFS version of the MFS function Delete.
  27487. vRefNum can hold a volume reference number or a working directory reference
  27488. number. dirID holds a directory ID.
  27489.  
  27490. HDelete calls the function PBHDelete, documented in the File Manager chapter of
  27491. Volume IV.
  27492.  
  27493.  
  27494. Trap macro  _HDelete
  27495.  
  27496. Parameter block
  27497.     —>  12  ioCompletion    pointer
  27498.     <—  16  ioResult        word
  27499.     —>  18  ioNamePtr       pointer
  27500.     —>  22  ioVRefNum       word
  27501.     —>  48  ioDirID         long word
  27502.  
  27503.     PBHDelete is identical to PBDelete except that it accepts a
  27504. directory ID in ioDirID. PBHDelete can be used to delete an empty
  27505. directory as well.
  27506.  
  27507. Result codes
  27508.  
  27509.     noErr       No error
  27510.     bdNamErr    Bad file name
  27511.     dirNFErr    Directory not found or incomplete pathname
  27512.     extFSErr    External file system
  27513.     fBsyErr     File busy, directory not empty, or working directory control block open
  27514.     fLckdErr    File locked
  27515.     fnfErr      File not found
  27516.     nsvErr      No such volume
  27517.     ioErr       I/O error
  27518.     vLckdErr    Software volume lock
  27519.     wPrErr      Hardware volume lock
  27520.  
  27521. æKY HGetFInfo
  27522. æFc Files.h
  27523. æT Function
  27524. æD pascal OSErr HGetFInfo(short vRefNum,long dirID,const Str255 fileName,FInfo *fndrInfo); 
  27525. æDT OSErr myVariable = HGetFInfo((short) vRefNum,(long) dirID,(const Str255) fileName,(FInfo *) fndrInfo);
  27526. æRI IV-149
  27527. æC Trap macro  _HGetFileInfo
  27528.  
  27529. Parameter block
  27530.     —>  12  ioCompletion    pointer
  27531.     <—  16  ioResult        word
  27532.     <–> 18  ioNamePtr       pointer
  27533.     —>  22  ioVRefNum       word
  27534.     <—  24  ioFRefNum       word
  27535.     —>  28  ioFDirIndex     word
  27536.     <—  30  ioFlAttrib      byte
  27537.     <—  32  ioFlFndrInfo    16 bytes
  27538.     <–> 48  ioDirID         long word
  27539.     <—  52  ioFlStBlk       word
  27540.     <—  54  ioFlLgLen       long word
  27541.     <—  58  ioFlPyLen       long word
  27542.     <—  62  ioFlRStBlk      word
  27543.     <—  64  ioFlRLgLen      long word
  27544.     <—  68  ioFlRPyLen      long word
  27545.     <—  72  ioFlCrDat       long word
  27546.     <—  76  ioFlMdDat       long word
  27547.  
  27548.     PBHGetFInfo is identical to PBGetFInfo except that it accepts a
  27549. directory ID in ioDirID.
  27550.  
  27551. Result codes
  27552.  
  27553.     noErr       No error
  27554.     bdNamErr    Bad file name
  27555.     dirNFErr    Directory not found or incomplete pathname
  27556.     extFSErr    External file system
  27557.     fnfErr      File not found
  27558.     ioErr       I/O error
  27559.     nsvErr      No such volume
  27560.     paramErr    No default volume
  27561.  
  27562. æKY HSetFInfo
  27563. æFc Files.h
  27564. æT Function
  27565. æD pascal OSErr HSetFInfo(short vRefNum,long dirID,const Str255 fileName,const FInfo *fndrInfo); 
  27566. æDT OSErr myVariable = HSetFInfo((short) vRefNum,(long) dirID,(const Str255) fileName,(const FInfo *) fndrInfo);
  27567. æRI IV-150
  27568. æC Trap macro  _HSetFileInfo
  27569.  
  27570. Parameter block
  27571.     —>  12  ioCompletion    pointer
  27572.     <—  16  ioResult        word
  27573.     —>  18  ioNamePtr       pointer
  27574.     —>  22  ioVRefNum       word
  27575.     —>  32  ioFlFndrInfo    16 bytes
  27576.     —>  48  ioDirID         long word
  27577.     —>  72  ioFlCrDat       long word
  27578.     —>  76  ioFlMdDat       long word
  27579.  
  27580.     PBHSetFInfo is identical to PBSetFInfo except that it accepts a
  27581. directory ID in ioDirID.
  27582.  
  27583. Result codes
  27584.  
  27585.     noErr       No error
  27586.     bdNamErr    Bad file name
  27587.     dirNFErr    Directory not found or incomplete pathname
  27588.     extFSErr    External file system
  27589.     fLckdErr    File locked
  27590.     fnfErr      File not found
  27591.     ioErr       I/O error
  27592.     nsvErr      No such volume
  27593.     vLckdErr    Software volume lock
  27594.     wPrErr      Hardware volume lock
  27595.  
  27596. æKY HSetFLock
  27597. æFc Files.h
  27598. æT Function
  27599. æD pascal OSErr HSetFLock(short vRefNum,long dirID,const Str255 fileName); 
  27600. æDT OSErr myVariable = HSetFLock((short) vRefNum,(long) dirID,(const Str255) fileName);
  27601. æRI IV-151, VI
  27602. æC 
  27603. HSetFLock locks a file: no new access paths to it can be created. It is an HFS
  27604. version of the MFS function SetFLock. It calls the function PBHSetFLock,
  27605. documented in the File Manager chapter of Volume IV.
  27606.  
  27607. Trap macro  _HSetFLock
  27608.  
  27609. Parameter block
  27610.     —>  12  ioCompletion    pointer
  27611.     <—  16  ioResult        word
  27612.     —>  18  ioNamePtr       pointer
  27613.     —>  22  ioVRefNum       word
  27614.     —>  48  ioDirID         long word
  27615.  
  27616.     PBHSetFLock is identical to PBSetFLock except that it accepts a
  27617. directory ID in ioDirID.
  27618.  
  27619. Result codes
  27620.  
  27621.     noErr       No error
  27622.     dirNFErr    Directory not found or incomplete pathname
  27623.     extFSErr    External file system
  27624.     fnfErr      File not found
  27625.     ioErr       I/O error
  27626.     nsvErr      No such volume
  27627.     vLckdErr    Software volume lock
  27628.     wPrErr      Hardware volume lock
  27629.  
  27630. æKY HRstFLock
  27631. æFc Files.h
  27632. æT Function
  27633. æD pascal OSErr HRstFLock(short vRefNum,long dirID,const Str255 fileName); 
  27634. æDT OSErr myVariable = HRstFLock((short) vRefNum,(long) dirID,(const Str255) fileName);
  27635. æRI IV-152, VI
  27636. æC 
  27637. HRstFLock unlocks a file. It is an HFS version of the MFS function RstFLock. It
  27638. calls the function PBHRstFLock, documented in the File Manager chapter of Volume
  27639. IV.
  27640.  
  27641. Trap macro  _HRstFLock
  27642.  
  27643. Parameter block
  27644.     —>  12  ioCompletion    pointer
  27645.     <—  16  ioResult        word
  27646.     —>  18  ioNamePtr       pointer
  27647.     —>  22  ioVRefNum       word
  27648.     —>  48  ioDirID         long word
  27649.  
  27650.     PBHRstFLock is identical to PBRstFLock except that it accepts a
  27651. directory ID in ioDirID.
  27652.  
  27653. Result codes
  27654.  
  27655.     noErr       No error
  27656.     dirNFErr    Directory not found or incomplete pathname
  27657.     extFSErr    External file system
  27658.     fnfErr      File not found
  27659.     ioErr       I/O error
  27660.     nsvErr      No such volume
  27661.     vLckdErr    Software volume lock
  27662.     wPrErr      Hardware volume lock
  27663.  
  27664. æKY HRename
  27665. æFc Files.h
  27666. æT Function
  27667. æD pascal OSErr HRename(short vRefNum,long dirID,const Str255 oldName,const Str255 newName); 
  27668. æDT OSErr myVariable = HRename((short) vRefNum,(long) dirID,(const Str255) oldName,(const Str255) newName);
  27669. æRI IV-154, VI
  27670. æC 
  27671. HRename changes the name of a file or directory. It is an HFS version of the MFS
  27672. function Rename. It calls the function PBHRename, documented in the File Manager
  27673. chapter of Volume IV.
  27674.  
  27675. Trap macro  _Rename
  27676.  
  27677. Parameter block
  27678.     —>  12  ioCompletion    pointer
  27679.     <—  16  ioResult        word
  27680.     —>  18  ioNamePtr       pointer
  27681.     —>  22  ioVRefNum       word
  27682.     —>  26  ioVersNum       byte
  27683.     —>  28  ioMisc          pointer
  27684.  
  27685.     Given a pointer to a file name in ioNamePtr (and on flat volumes, a
  27686. version number in ioVersNum), PBRename changes the name of the file to
  27687. the name pointed to by ioMisc. (If the name pointed to by ioNamePtr
  27688. contains one or more colons, so must the name pointed to by ioMisc.)
  27689. Access paths currently in use aren’t affected. Given a pointer to a
  27690. volume name in ioNamePtr or a volume reference number in ioVRefNum, it
  27691. changes the name of the volume to the name pointed to by ioMisc. If a
  27692. volume to be renamed is specified by its volume reference number,
  27693. ioNamePtr can be NIL.
  27694.  
  27695. Warning:
  27696.  
  27697.     If a volume to be renamed is specified by its volume name, be
  27698.     sure that it ends with a colon, or Rename will consider it a
  27699.     file name.
  27700.  
  27701. Result codes
  27702.  
  27703.     noErr       No error
  27704.     bdNamErr    Bad file name
  27705.     dirFulErr   File directory full
  27706.     dupFNErr    Duplicate file name and version
  27707.     extFSErr    External file system
  27708.     fLckdErr    File locked
  27709.     fnfErr      File not found
  27710.     fsRnErr     Problem during rename
  27711.     ioErr       I/O error
  27712.     nsvErr      No such volume
  27713.     paramErr    No default volume
  27714.     vLckdErr    Software volume lock
  27715.     wPrErr      Hardware volume lock
  27716.  
  27717. æKY CatMove
  27718. æFc Files.h
  27719. æT Function
  27720. æD pascal OSErr CatMove(short vRefNum,long dirID,const Str255 oldName,long newDirID,
  27721.     const Str255 newName); 
  27722. æDT OSErr myVariable = CatMove((short) vRefNum,(long) dirID,(const Str255) oldName,(long) newDirID,(
  27723.     const) Str255 newName);
  27724. æRT 218
  27725. æRI IV-157, VI
  27726. æC 
  27727. CatMove is a high-level function that calls PBCatMove.
  27728.  
  27729. Trap macro  _CatMove
  27730.  
  27731. Parameter block
  27732.     —>  12  ioCompletion    pointer
  27733.     <—  16  ioResult        word
  27734.     —>  18  ioNamePtr       pointer
  27735.     —>  22  ioVRefNum       word
  27736.     —>  28  ioNewName       pointer
  27737.     —>  36  ioNewDirID      long word
  27738.     —>  48  ioDirID         long word
  27739.  
  27740.     PBCatMove moves files or directories from one directory to another.
  27741. The name of the file or directory to be moved is pointed to by
  27742. ioNamePtr; ioVRefNum contains either the volume reference number or
  27743. working directory reference number. A directory ID can be specified in
  27744. ioDirID. The name and directory ID of the directory to which the file
  27745. or directory is to be moved are specified by ioNewName and ioNewDirID.
  27746.  
  27747.     PBCatMove is strictly a file catalog operation; it does not actually
  27748. change the location of the file or directory on the disk. PBCatMove
  27749. cannot move a file or directory to another volume (that is, ioVRefNum is
  27750. used in specifying both the source and the destination). It also cannot
  27751. be used to rename files or directories; for that, use PBHRename.
  27752.  
  27753. Result codes
  27754.  
  27755.     noErr       No error
  27756.     badMovErr   Attempt to move into offspring
  27757.     bdNamErr    Bad file name or attempt to move into a file
  27758.     dupFNErr    Duplicate file name and version
  27759.     fnfErr      File not found
  27760.     ioErr       I/O error
  27761.     nsvErr      No such volume
  27762.     paramErr    No default volume
  27763.     vLckdErr    Software volume lock
  27764.     wPrErr      Hardware volume lock
  27765.  
  27766. æKY OpenWD
  27767. æFc Files.h
  27768. æT Function
  27769. æD pascal OSErr OpenWD(short vRefNum,long dirID,long procID,short *wdRefNum); 
  27770. æDT OSErr myVariable = OpenWD((short) vRefNum,(long) dirID,(long) procID,(short *) wdRefNum);
  27771. æRT 218
  27772. æRI IV-158, VI
  27773. æC 
  27774. OpenWD is a high-level function that calls PBOpenWD.
  27775.  
  27776. Trap macro  _OpenWD
  27777.  
  27778. Parameter block
  27779.     —>  12  ioCompletion    pointer
  27780.     <—  16  ioResult        word
  27781.     —>  18  ioNamePtr       pointer
  27782.     <–> 22  ioVRefNum       word
  27783.     —>  28  ioWDProcID      long word
  27784.     —>  48  ioWDDirID       long word
  27785.  
  27786.     PBOpenWD takes the directory specified by ioVRefNum, ioWDDirID, and
  27787. ioWDProcID and makes it a working directory. (You can also specify the
  27788. directory using a combination of partial pathname and directory ID.)  It
  27789. returns a working directory reference number in ioVRefNum that can be
  27790. used in subsequent calls.
  27791.  
  27792.     If a given directory has already been made a working directory using
  27793. the same ioWDProcID, no new working directory will be opened; instead,
  27794. the existing working directory reference number will be returned. If a
  27795. given directory was already made a working directory using a different
  27796. ioWDProcID, a new working directory reference number is returned.
  27797.  
  27798. Result codes
  27799.  
  27800.     noErr       No error
  27801.     tmwdoErr    Too many working directories open
  27802.  
  27803. æKY CloseWD
  27804. æFc Files.h
  27805. æT Function
  27806. æD pascal OSErr CloseWD(short wdRefNum); 
  27807. æDT OSErr myVariable = CloseWD((short) wdRefNum);
  27808. æRT 218
  27809. æRI IV-158, VI
  27810. æC
  27811. CloseWD is a high-level function that calls PBCloseWD.
  27812.  
  27813. Trap macro  _CloseWD
  27814.  
  27815. Parameter block
  27816.     —>  12  ioCompletion    pointer
  27817.     <—  16  ioResult        word
  27818.     —>  22  ioVRefNum       word
  27819.  
  27820.     PBCloseWD releases the working directory whose working directory
  27821. reference number is specified in ioVRefNum.
  27822.  
  27823. Note:  
  27824.  
  27825.     If a volume reference number is specified in ioVRefNum, PBCloseWD
  27826.     does nothing.
  27827.  
  27828. Result codes
  27829.  
  27830.     noErr   No error
  27831.     nsvErr  No such volume
  27832.  
  27833. æKY GetWDInfo
  27834. æFc Files.h
  27835. æT Function
  27836. æD pascal OSErr GetWDInfo(short wdRefNum,short *vRefNum,long *dirID,long *procID); 
  27837. æDT OSErr myVariable = GetWDInfo((short) wdRefNum,(short *) vRefNum,(long *) dirID,(long *) procID);
  27838. æRT 218
  27839. æRI IV-159, VI
  27840. æC 
  27841. GetWDInfo is a high-level function that calls PBGetWDInfo.
  27842.  
  27843. Trap macro  _GetWDInfo
  27844.  
  27845. Parameter block
  27846.     —>  12  ioCompletion    pointer
  27847.     <—  16  ioResult        word
  27848.     <—  18  ioNamePtr       pointer
  27849.     <–> 22  ioVRefNum       word
  27850.     —>  26  ioWDIndex       word
  27851.     <–> 28  ioWDProcID      long word
  27852.     <–> 32  ioWDVRefNum     word
  27853.     <—  48  ioWDDirID       long word
  27854.  
  27855.     PBGetWDInfo returns information about the specified working
  27856. directory. The working directory can be specified either by its working
  27857. directory reference number in ioVRefNum (in which case ioWDIndex should
  27858. be 0), or by its index number in ioWDIndex. In the latter case, if
  27859. ioVRefNum is nonzero, it’s interpreted as a volume specification (volume
  27860. reference number or drive number), and only working directories on that
  27861. volume are indexed.
  27862.  
  27863.     IOWDVRefNum always returns the volume reference number. IOVRefNum
  27864. returns a working directory reference number when a working directory
  27865. reference number is passed in that field; otherwise, it returns a volume
  27866. reference number. The volume name is returned in ioNamePtr.
  27867.  
  27868.     If IOWDProcID is nonzero, only working directories with that
  27869. identifier are indexed; otherwise all working directories are indexed.
  27870.  
  27871. Result codes
  27872.  
  27873.     noErr   No error
  27874.     nsvErr  No such volume
  27875.  
  27876. æKY PBExchangeFiles
  27877. æFc Files.h
  27878. æT Function
  27879. æD pascal OSErr PBExchangeFiles(HParmBlkPtr paramBlock,Boolean async); 
  27880. æDT OSErr myVariable = PBExchangeFiles((HParmBlkPtr) paramBlock,(Boolean) async);
  27881. æC 
  27882. Parameter Block 
  27883. ¨   16  ioResult       word
  27884. Æ   18  ioNamePtr      string pointer
  27885. Æ   22  ioVRefNum      word
  27886. Æ   28  ioDestNamePtr  string pointer
  27887. Æ   36  ioDestDirID    long
  27888. Æ   48  ioSrcDirID     long
  27889.  
  27890. You should use PBExchangeFiles if your application needs to preserve the file ID
  27891. after moving the data into a new file. Typically, you use PBExchangeFiles after
  27892. creating a new file during a safe save. You must specify both files, which must
  27893. exist on the same volume. The file specified by [ioDestDirID, ioDestNamePtr] is
  27894. exchanged with the file specified by [ioSrcDirID, ioNamePtr]. Both forks of the
  27895. files are exchanged. Modification dates in the catalog record are exchanged,
  27896. along with the fields accessed by HFS to locate the data of the files. All other
  27897. catalog information remains unchanged.
  27898.  
  27899. PBExchangeFiles works on either open or closed files. If either file is open,
  27900. PBExchangeFiles updates any file control blocks associated with the file.
  27901.  
  27902. PBExchangeFiles does not require that file IDs exist for the files being
  27903. exchanged.
  27904.  
  27905. Result codes:
  27906.  
  27907. extFSErr          -58  External file system
  27908. ioErr             -36  I/O error
  27909. nsvErr            -35  No such volume
  27910. fnfErr            -43  File not found
  27911. fLckdErr          -45  One or both files locked
  27912. volOfflinErr      -53  Volume is off-line
  27913. wrgVolTypeErr    -123  Not an HFS volume
  27914. fidNotFoundErr  -1300  File not found
  27915. fidExists       -1301  File ID already exists
  27916. notAFileErr     -1302  Specified file is a directory
  27917. diffVolErr      -xxxx  Volume specifications in pathnames are not equivalent
  27918.  
  27919. æKY PBCreateFileID
  27920. æFc Files.h
  27921. æT Function
  27922. æD pascal OSErr PBCreateFileID(HParmBlkPtr paramBlock,Boolean async); 
  27923. æDT OSErr myVariable = PBCreateFileID((HParmBlkPtr) paramBlock,(Boolean) async);
  27924. æC 
  27925. Parameter Block 
  27926.   ¨   16  ioResult    word
  27927.   Æ   18  ioNamePtr   string pointer
  27928.   Æ   22  ioVRefNum   word
  27929.   Æ   48  ioSrcDirID  long
  27930.   ¨   54  ioFileID    long 
  27931.  
  27932. Given a volume reference number, file name, and parent directory ID,
  27933. PBCreateFileID creates a record to hold the name and parent directory ID of the
  27934. specified file. The actual value of the file ID is the same as the file number
  27935. stored in the file record. If a file ID already exists for the file, the ID
  27936. value is returned in ioFileID.
  27937.  
  27938. Result codes
  27939. extFSErr          -58  External file system
  27940. ioErr             -36  I/O error
  27941. nsvErr            -35  No such volume
  27942. volOfflinErr      -53  Volume is offline
  27943. vLckdErr          -46  Software volume lock
  27944. wPrErr            -44  Hardware volume lock
  27945. wrgVolTypeErr    -123  Not an HFS volume
  27946. fidNotFoundErr  -1300  File not found
  27947. fidExists       -1301  File ID already exists
  27948. notAFileErr     -1302  Specified file is a directory
  27949.  
  27950. æKY PBResolveFileID
  27951. æFc Files.h
  27952. æT Function
  27953. æD 
  27954. pascal OSErr PBResolveFileID(HParmBlkPtr paramBlock,Boolean async); 
  27955. æDT OSErr myVariable = PBResolveFileID((HParmBlkPtr) paramBlock,(Boolean) async);
  27956. æC 
  27957. Parameter Block 
  27958.   ¨   16  ioResult    word
  27959.   ´   18  ioNamePtr   string pointer
  27960.   Æ   22  ioVRefNum   word
  27961.   ¨   48  ioSrcDirID  long
  27962.   Æ   54  ioFileID    long 
  27963.  
  27964. PBResolveFileID returns the filename and parent directory ID of the file
  27965. referred to by file ID in the ioFileID field. It places the filename in the
  27966. string pointed to by ioNamePtr and the directory ID in ioSrcDirID. You must
  27967. allocate memory <how much?> for the string before you make the call. If the name
  27968. string is NIL, PBResolveFileID returns only the parent directory ID. If the name
  27969. string is not NIL but is only a volume name, PBResolveFileID ignores the value
  27970. in ioVRefNum, uses the volume name instead, and overwrites the name string with
  27971. the filename. A return code of fidNotFound means that the specified file ID has
  27972. become invalid either because the file was deleted or the file ID was destroyed
  27973. by PBDeleteFileID.
  27974.  
  27975. Result codes:
  27976.  
  27977. extFSErr          -58  External file system
  27978. ioErr             -36  I/O error
  27979. nsvErr            -35  No such volume
  27980. volOfflinErr      -53  Volume is off-line
  27981. wrgVolTypeErr    -123  Not an HFS volume
  27982. fidNotFoundErr  -1300  File ID not found
  27983. fidExists       -1301  File ID already exists
  27984. notAFileErr     -1302  Specified file is a directory
  27985.  
  27986. æKY PBDeleteFileID
  27987. æFc Files.h
  27988. æT Function
  27989. æD pascal OSErr PBDeleteFileID(HParmBlkPtr paramBlock,Boolean async); 
  27990. æDT OSErr myVariable = PBDeleteFileID((HParmBlkPtr) paramBlock,(Boolean) async);
  27991. æC 
  27992. Parameter Block 
  27993.   ¨   16  ioResult   word
  27994.   Æ   18  ioNamePtr  string pointer
  27995.   Æ   22  ioVRefNum  word
  27996.   Æ   54  ioFileID   long 
  27997.  
  27998. PBDeleteFileID invalidates a file ID on the volume specified by ioVRefNum or
  27999. ioNamePtr. After it has invalidated a file ID, the File Manager can no longer
  28000. resolve it to a filename and parent directory ID. The file ID is invalidated
  28001. whether or not the target file referenced by that ID still exists.
  28002.  
  28003. Result codes:
  28004.  
  28005. extFSErr          -58  External file system
  28006. ioErr             -36  I/O error
  28007. nsvErr            -35  No such volume
  28008. volOfflinErr      -53  Volume is offline
  28009. vLckdErr          -46  Software volume lock
  28010. wPrErr            -44  Hardware volume lock
  28011. wrgVolTypeErr    -123  Not an HFS volume
  28012. fidNotFoundErr  -1300  File ID not found
  28013. fidExists       -1301  File ID already exists
  28014. notAFileErr     -1302  Specified file is a directory
  28015.  
  28016. æKY PBDTGetPath
  28017. æFc Files.h
  28018. æT Function
  28019. æD pascal OSErr PBDTGetPath(DTPBPtr paramBlock,Boolean async); 
  28020. æDT OSErr myVariable = PBDTGetPath((DTPBPtr) paramBlock,(Boolean) async);
  28021. æC 
  28022.  
  28023. æKY PBDTCloseDown
  28024. æFc Files.h
  28025. æT Function
  28026. æD pascal OSErr PBDTCloseDown(DTPBPtr paramBlock,Boolean async); 
  28027. æDT OSErr myVariable = PBDTCloseDown((DTPBPtr) paramBlock,(Boolean) async);
  28028. æC 
  28029.  
  28030. æKY PBDTAddIcon
  28031. æFc Files.h
  28032. æT Function
  28033. æD pascal OSErr PBDTAddIcon(DTPBPtr paramBlock,Boolean async); 
  28034. æDT OSErr myVariable = PBDTAddIcon((DTPBPtr) paramBlock,(Boolean) async);
  28035. æRI 
  28036.  
  28037. æC 
  28038.  
  28039. æKY PBDTGetIcon
  28040. æFc Files.h
  28041. æT Function
  28042. æD pascal OSErr PBDTGetIcon(DTPBPtr paramBlock,Boolean async); 
  28043. æDT OSErr myVariable = PBDTGetIcon((DTPBPtr) paramBlock,(Boolean) async);
  28044. æRI 
  28045.  
  28046. æC 
  28047.  
  28048. æKY PBDTGetIconInfo
  28049. æFc Files.h
  28050. æT Function
  28051. æD pascal OSErr PBDTGetIconInfo(DTPBPtr paramBlock,Boolean async); 
  28052. æDT OSErr myVariable = PBDTGetIconInfo((DTPBPtr) paramBlock,(Boolean) async);
  28053. æRI 
  28054.  
  28055. æC 
  28056.  
  28057. æKY PBDTAddAPPL
  28058. æFc Files.h
  28059. æT Function
  28060. æD pascal OSErr PBDTAddAPPL(DTPBPtr paramBlock,Boolean async); 
  28061. æDT OSErr myVariable = PBDTAddAPPL((DTPBPtr) paramBlock,(Boolean) async);
  28062. æRI 
  28063.  
  28064. æC 
  28065.  
  28066. æKY PBDTRemoveAPPL
  28067. æFc Files.h
  28068. æT Function
  28069. æD pascal OSErr PBDTRemoveAPPL(DTPBPtr paramBlock,Boolean async); 
  28070. æDT OSErr myVariable = PBDTRemoveAPPL((DTPBPtr) paramBlock,(Boolean) async);
  28071. æRI 
  28072.  
  28073. æC 
  28074.  
  28075. æKY PBDTGetAPPL
  28076. æFc Files.h
  28077. æT Function
  28078. æD pascal OSErr PBDTGetAPPL(DTPBPtr paramBlock,Boolean async); 
  28079. æDT OSErr myVariable = PBDTGetAPPL((DTPBPtr) paramBlock,(Boolean) async);
  28080. æRI 
  28081.  
  28082. æC 
  28083.  
  28084. æKY PBDTSetComment
  28085. æFc Files.h
  28086. æT Function
  28087. æD pascal OSErr PBDTSetComment(DTPBPtr paramBlock,Boolean async); 
  28088. æDT OSErr myVariable = PBDTSetComment((DTPBPtr) paramBlock,(Boolean) async);
  28089. æC 
  28090.  
  28091. æKY PBDTRemoveComment
  28092. æFc Files.h
  28093. æT Function
  28094. æD pascal OSErr PBDTRemoveComment(DTPBPtr paramBlock,Boolean async); 
  28095. æDT OSErr myVariable = PBDTRemoveComment((DTPBPtr) paramBlock,(Boolean) async);
  28096. æRI 
  28097.  
  28098. æC 
  28099.  
  28100. æKY PBDTGetComment
  28101. æFc Files.h
  28102. æT Function
  28103. æD pascal OSErr PBDTGetComment(DTPBPtr paramBlock,Boolean async); 
  28104. æDT OSErr myVariable = PBDTGetComment((DTPBPtr) paramBlock,(Boolean) async);
  28105. æRI 
  28106.  
  28107. æC 
  28108.  
  28109. æKY PBDTFlush
  28110. æFc Files.h
  28111. æT Function
  28112. æD pascal OSErr PBDTFlush(DTPBPtr paramBlock,Boolean async); 
  28113. æDT OSErr myVariable = PBDTFlush((DTPBPtr) paramBlock,(Boolean) async);
  28114. æRI 
  28115.  
  28116. æC 
  28117.  
  28118. æKY PBDTReset
  28119. æFc Files.h
  28120. æT Function
  28121. æD pascal OSErr PBDTReset(DTPBPtr paramBlock,Boolean async); 
  28122. æDT OSErr myVariable = PBDTReset((DTPBPtr) paramBlock,(Boolean) async);
  28123. æRI 
  28124.  
  28125. æC 
  28126.  
  28127. æKY PBDTGetInfo
  28128. æFc Files.h
  28129. æT Function
  28130. æD pascal OSErr PBDTGetInfo(DTPBPtr paramBlock,Boolean async); 
  28131. æDT OSErr myVariable = PBDTGetInfo((DTPBPtr) paramBlock,(Boolean) async);
  28132. æRI 
  28133.  
  28134. æC 
  28135.  
  28136. æKY PBDTOpenInform
  28137. æFc Files.h
  28138. æT Function
  28139. æD pascal OSErr PBDTOpenInform(DTPBPtr paramBlock,Boolean async); 
  28140. æDT OSErr myVariable = PBDTOpenInform((DTPBPtr) paramBlock,(Boolean) async);
  28141. æRI 
  28142.  
  28143. æC 
  28144.  
  28145. æKY PBDTDelete
  28146. æFc Files.h
  28147. æT Function
  28148. æD pascal OSErr PBDTDelete(DTPBPtr paramBlock,Boolean async); 
  28149. æDT OSErr myVariable = PBDTDelete((DTPBPtr) paramBlock,(Boolean) async);
  28150. æRI 
  28151.  
  28152. æC 
  28153.  
  28154. æKY MakeFSSpec
  28155. æFc Files.h
  28156. æT Function
  28157. æD /*  FSSpec Glue  */
  28158. pascal OSErr MakeFSSpec(short vRefNum,long dirID,StringPtr fileName); 
  28159. æDT /*  FSSpec Glue  */
  28160. pascal OSErr myVariable = MakeFSSpec((short) vRefNum,(long) dirID,(StringPtr) fileName);
  28161. æRI VI
  28162. æC 
  28163. You use the MakeFSSpec function to establish the canonical form of the name for
  28164. a file, folder, or volume.
  28165.  
  28166. FUNCTION MakeFSSpec (vRefNum: Integer; dirID: LongInt; fileName: Str255; VAR
  28167.                      canonicalFile: CanonicalFileSpec) : OSErr;
  28168.  
  28169. MakeFSSpec places the canonical form of the specified file reference in the
  28170. CanonicalFileSpec parameter. (See “Identifying Files, Folders, and Volumes” for
  28171. a description of the FSSpec record.)
  28172.  
  28173. The vRefNum parameter is the volume reference number, a working directory
  28174. reference number, a drive number, or 0 for the default volume.
  28175.  
  28176. The dirID parameter is the parent directory ID of the target object. If the
  28177. directory is sufficiently specified by either vRefNum or fileName, dirID can be
  28178. 0. If you explicitly specify dirID (that is, if it is any value other than 0),
  28179. and if vRefNum is a working directory reference number, dirID overrides the
  28180. directory ID included in vRefNum.
  28181.  
  28182. The fileName parameter is a full or partial pathname. If it is a full pathname,
  28183. MakeFSSpec ignores vRefNum and dirID. A partial pathname might identify only the
  28184. final target, or it might include one or more parent folder names. If fileName
  28185. is a partial pathname, vRefNum, dirID, or both must be valid.
  28186.  
  28187. You can pass the input to MakeFSSpec in any of the four ways described in 
  28188. “Identifying Files, Folders, and Volumes” earlier in this chapter. See “Using
  28189. the File Manager” for a summary of the how MakeFSSpec accepts input and how it
  28190. fills in the FSSpec record for files, folders, and volumes.
  28191.  
  28192. In addition to the result code listed here, MakeFSSpec can return a number of
  28193. different File Manager or Memory Manager error codes.
  28194.  
  28195. Result codes
  28196. paramErr  -50  Output is NIL
  28197.  
  28198. æKY FSpOpenDF
  28199. æFc Files.h
  28200. æT Function
  28201. æD 
  28202. pascal OSErr FSpOpenDF(FSSpecPtr spec,char permission,short *refNum); 
  28203. æDT OSErr myVariable = FSpOpenDF((FSSpecPtr) spec,(char) permission,(short *) refNum);
  28204. æRI 
  28205.  
  28206. æC 
  28207.  
  28208. æKY FSpOpenRF
  28209. æFc Files.h
  28210. æT Function
  28211. æD 
  28212. pascal OSErr FSpOpenRF(FSSpecPtr spec,char permission,short *refNum); 
  28213. æDT OSErr myVariable = FSpOpenRF((FSSpecPtr) spec,(char) permission,(short *) refNum);
  28214. æRI 
  28215.  
  28216. æC 
  28217.  
  28218. æKY FSpCreate
  28219. æFc Files.h
  28220. æT Function
  28221. æD 
  28222. pascal OSErr FSpCreate(FSSpecPtr spec,OSType creator,OSType fileType); 
  28223. æDT OSErr myVariable = FSpCreate((FSSpecPtr) spec,(OSType) creator,(OSType) fileType);
  28224. æRI 
  28225.  
  28226. æC 
  28227.  
  28228. æKY FSpDirCreate
  28229. æFc Files.h
  28230. æT Function
  28231. æD 
  28232. pascal OSErr FSpDirCreate(FSSpecPtr spec,long *createdDirID); 
  28233. æDT OSErr myVariable = FSpDirCreate((FSSpecPtr) spec,(long *) createdDirID);
  28234. æRI 
  28235.  
  28236. æC 
  28237.  
  28238. æKY FSpDelete
  28239. æFc Files.h
  28240. æT Function
  28241. æD 
  28242. pascal OSErr FSpDelete(FSSpecPtr spec); 
  28243. æDT OSErr myVariable = FSpDelete((FSSpecPtr) spec);
  28244. æRI 
  28245.  
  28246. æC 
  28247.  
  28248. æKY FSpGetFInfo
  28249. æFc Files.h
  28250. æT Function
  28251. æD 
  28252. pascal OSErr FSpGetFInfo(FSSpecPtr spec,FInfo *fndrInfo); 
  28253. æDT OSErr myVariable = FSpGetFInfo((FSSpecPtr) spec,(FInfo *) fndrInfo);
  28254. æRI 
  28255.  
  28256. æC 
  28257.  
  28258. æKY FSpSetFInfo
  28259. æFc Files.h
  28260. æT Function
  28261. æD 
  28262. pascal OSErr FSpSetFInfo(FSSpecPtr spec,FInfo *fndrInfo); 
  28263. æDT OSErr myVariable = FSpSetFInfo((FSSpecPtr) spec,(FInfo *) fndrInfo);
  28264. æRI 
  28265.  
  28266. æC 
  28267.  
  28268. æKY FSpSetFLock
  28269. æFc Files.h
  28270. æT Function
  28271. æD 
  28272. pascal OSErr FSpSetFLock(FSSpecPtr spec); 
  28273. æDT OSErr myVariable = FSpSetFLock((FSSpecPtr) spec);
  28274. æRI 
  28275.  
  28276. æC 
  28277.  
  28278. æKY FSpRstFLock
  28279. æFc Files.h
  28280. æT Function
  28281. æD 
  28282. pascal OSErr FSpRstFLock(FSSpecPtr spec); 
  28283. æDT OSErr myVariable = FSpRstFLock((FSSpecPtr) spec);
  28284. æRI 
  28285.  
  28286. æC 
  28287.  
  28288. æKY FSpRename
  28289. æFc Files.h
  28290. æT Function
  28291. æD 
  28292. pascal OSErr FSpRename(FSSpecPtr spec,StringPtr newName); 
  28293. æDT OSErr myVariable = FSpRename((FSSpecPtr) spec,(StringPtr) newName);
  28294. æRI 
  28295.  
  28296. æC 
  28297.  
  28298. æKY FSpCatMove
  28299. æFc Files.h
  28300. æT Function
  28301. æD 
  28302. pascal OSErr FSpCatMove(FSSpecPtr source,FSSpecPtr dest); 
  28303. æDT OSErr myVariable = FSpCatMove((FSSpecPtr) source,(FSSpecPtr) dest);
  28304. æRI 
  28305.  
  28306. æC 
  28307.  
  28308. æKY FSpOpenResFile
  28309. æFc Files.h
  28310. æT Function
  28311. æD 
  28312. pascal short FSpOpenResFile(FSSpecPtr spec,char permission); 
  28313. æDT short myVariable = FSpOpenResFile((FSSpecPtr) spec,(char) permission);
  28314. æRI 
  28315.  
  28316. æC 
  28317.  
  28318. æKY FSpCreateResFile
  28319. æFc Files.h
  28320. æT Function
  28321. æD 
  28322. pascal void FSpCreateResFile(FSSpecPtr spec); 
  28323. æDT 
  28324. FSpCreateResFile((FSSpecPtr) spec);
  28325. æRI 
  28326.  
  28327. æC 
  28328.  
  28329.  
  28330. æKY FixMath.h
  28331. æKL Fix2Frac
  28332. Fix2Long
  28333. Fix2X
  28334. FixATan2
  28335. FixDiv
  28336. Frac2Fix
  28337. Frac2X
  28338. FracCos
  28339. FracDiv
  28340. FracMul
  28341. FracSin
  28342. FracSqrt
  28343. Long2Fix
  28344. X2Fix
  28345. X2Frac
  28346.  
  28347.  
  28348. æKY Fix2Frac
  28349. æFc FixMath.h
  28350. æT Function
  28351. æTN A841
  28352. æD pascal Fract Fix2Frac(Fixed x)
  28353.     = 0xA841; 
  28354. æDT Fract myVariable = Fix2Frac((Fixed) x);
  28355. æRI IV-65
  28356. æC 
  28357. Long2Fix, Fix2Long, Fix2Frac, and Frac2Fix convert between fixed-point types.
  28358.  
  28359. Examples
  28360.  
  28361. Examples of the use of these fixed-point functions are provided below; all numbers
  28362. are decimal unless otherwise noted.
  28363.  
  28364. Function                                 Result      Comment
  28365. FixDiv    (X2Fix(1.95), X2Fix(1.30))     $00018000    1.5 = 01.10 bin
  28366. FracDiv   (X2Frac(1.95), X2Frac(1.30))   $60000000    1.5 = 01.10 bin
  28367. FracMul   (X2Frac(1.50), X2Frac(1.30))   $7CCCCCCD    1.95 rounded
  28368. FracSqrt  (X2Frac(1.96))                 $5999999A    1.4 rounded
  28369. FracSin   (X2Fix(3.1416015625))          $00000000    0
  28370. FracCos   (X2Fix(3.1416015625))          $C0000000   -1
  28371. Fix2Long  (X2Fix(1.75))                  $00000002    2
  28372. Fix2Frac  (X2Fix(1.75))                  $70000000    1.75 = 01.11 bin
  28373. Frac2Fix  (X2Frac(1.75))                 $0001C000    1.75 = 01.11 bin
  28374. FixATan2  (X2Fix(1.00), X2Fix(1.00))     $0000C910    0.C910 hex = X2Fix (π/4)
  28375. FixDiv    (X2Fix(-1.95), X2Fix(1.30))    $FFFE8000   -1.5
  28376. FracDiv   (X2Frac(-1.95), X2Frac(1.30))  $A0000000   -1.5
  28377. FracMul   (X2Frac(-1.50), X2Frac(1.30))  $83333333   -1.95 rounded
  28378. FracSin   (X2Fix(-3.1416015625))         $00000000    0
  28379. FracCos   (X2Fix(-3.1416015625))         $C0000000   -1
  28380. Fix2Long  (X2Fix(-1.75))                 $FFFFFFFE   -2
  28381. Fix2Frac  (X2Fix(-1.75))                 $90000000   -1.75
  28382. Frac2Fix  (X2Frac(-1.75))                $FFFE4000   -1.75
  28383. FixATan2  (X2Fix(-1.00), X2Fix(-1.00))   $FFFDA4D0   -3*X2Fix(π/4)=3*0.C910 hex
  28384.  
  28385. æKY Fix2Long
  28386. æFc FixMath.h
  28387. æT Function
  28388. æTN A840
  28389. æD pascal long Fix2Long(Fixed x)
  28390.     = 0xA840; 
  28391. æDT long myVariable = Fix2Long((Fixed) x);
  28392. æRI IV-65
  28393. æC 
  28394. Long2Fix, Fix2Long, Fix2Frac, and Frac2Fix convert between fixed-point types.
  28395.  
  28396. Examples
  28397.  
  28398. Examples of the use of these fixed-point functions are provided below; all numbers
  28399. are decimal unless otherwise noted.
  28400.  
  28401. Function                                 Result      Comment
  28402. FixDiv    (X2Fix(1.95), X2Fix(1.30))     $00018000    1.5 = 01.10 bin
  28403. FracDiv   (X2Frac(1.95), X2Frac(1.30))   $60000000    1.5 = 01.10 bin
  28404. FracMul   (X2Frac(1.50), X2Frac(1.30))   $7CCCCCCD    1.95 rounded
  28405. FracSqrt  (X2Frac(1.96))                 $5999999A    1.4 rounded
  28406. FracSin   (X2Fix(3.1416015625))          $00000000    0
  28407. FracCos   (X2Fix(3.1416015625))          $C0000000   -1
  28408. Fix2Long  (X2Fix(1.75))                  $00000002    2
  28409. Fix2Frac  (X2Fix(1.75))                  $70000000    1.75 = 01.11 bin
  28410. Frac2Fix  (X2Frac(1.75))                 $0001C000    1.75 = 01.11 bin
  28411. FixATan2  (X2Fix(1.00), X2Fix(1.00))     $0000C910    0.C910 hex = X2Fix (π/4)
  28412. FixDiv    (X2Fix(-1.95), X2Fix(1.30))    $FFFE8000   -1.5
  28413. FracDiv   (X2Frac(-1.95), X2Frac(1.30))  $A0000000   -1.5
  28414. FracMul   (X2Frac(-1.50), X2Frac(1.30))  $83333333   -1.95 rounded
  28415. FracSin   (X2Fix(-3.1416015625))         $00000000    0
  28416. FracCos   (X2Fix(-3.1416015625))         $C0000000   -1
  28417. Fix2Long  (X2Fix(-1.75))                 $FFFFFFFE   -2
  28418. Fix2Frac  (X2Fix(-1.75))                 $90000000   -1.75
  28419. Frac2Fix  (X2Frac(-1.75))                $FFFE4000   -1.75
  28420. FixATan2  (X2Fix(-1.00), X2Fix(-1.00))   $FFFDA4D0   -3*X2Fix(π/4)=3*0.C910 hex
  28421.  
  28422. æKY FixATan2
  28423. æFc FixMath.h
  28424. æT Function
  28425. æTN A818
  28426. æD pascal Fixed FixATan2(long x,long y)
  28427.     = 0xA818; 
  28428. æDT Fixed myVariable = FixATan2((long) x,(long) y);
  28429. æRI IV-65
  28430. æC 
  28431. FixATan2 returns the arctangent of y / x in radians. Note that FixATan2 effects
  28432. “arctan(type / type) --> Fixed”:
  28433.  
  28434.   arctan(LONGINT / LONGINT)  -->    Fixed
  28435.   arctan(Fixed / Fixed)      -->    Fixed
  28436.   arctan(Fract / Fract)      -->    Fixed
  28437.  
  28438. æKY Long2Fix
  28439. æFc FixMath.h
  28440. æT Function
  28441. æTN A83F
  28442. æD pascal Fixed Long2Fix(long x)
  28443.     = 0xA83F; 
  28444. æDT Fixed myVariable = Long2Fix((long) x);
  28445. æRI IV-65
  28446. æC 
  28447. Long2Fix, Fix2Long, Fix2Frac, and Frac2Fix convert between fixed-point types.
  28448.  
  28449. Examples
  28450.  
  28451. Examples of the use of these fixed-point functions are provided below; all numbers
  28452. are decimal unless otherwise noted.
  28453.  
  28454. Function                                 Result      Comment
  28455. FixDiv    (X2Fix(1.95), X2Fix(1.30))     $00018000    1.5 = 01.10 bin
  28456. FracDiv   (X2Frac(1.95), X2Frac(1.30))   $60000000    1.5 = 01.10 bin
  28457. FracMul   (X2Frac(1.50), X2Frac(1.30))   $7CCCCCCD    1.95 rounded
  28458. FracSqrt  (X2Frac(1.96))                 $5999999A    1.4 rounded
  28459. FracSin   (X2Fix(3.1416015625))          $00000000    0
  28460. FracCos   (X2Fix(3.1416015625))          $C0000000   -1
  28461. Fix2Long  (X2Fix(1.75))                  $00000002    2
  28462. Fix2Frac  (X2Fix(1.75))                  $70000000    1.75 = 01.11 bin
  28463. Frac2Fix  (X2Frac(1.75))                 $0001C000    1.75 = 01.11 bin
  28464. FixATan2  (X2Fix(1.00), X2Fix(1.00))     $0000C910    0.C910 hex = X2Fix (π/4)
  28465. FixDiv    (X2Fix(-1.95), X2Fix(1.30))    $FFFE8000   -1.5
  28466. FracDiv   (X2Frac(-1.95), X2Frac(1.30))  $A0000000   -1.5
  28467. FracMul   (X2Frac(-1.50), X2Frac(1.30))  $83333333   -1.95 rounded
  28468. FracSin   (X2Fix(-3.1416015625))         $00000000    0
  28469. FracCos   (X2Fix(-3.1416015625))         $C0000000   -1
  28470. Fix2Long  (X2Fix(-1.75))                 $FFFFFFFE   -2
  28471. Fix2Frac  (X2Fix(-1.75))                 $90000000   -1.75
  28472. Frac2Fix  (X2Frac(-1.75))                $FFFE4000   -1.75
  28473. FixATan2  (X2Fix(-1.00), X2Fix(-1.00))   $FFFDA4D0   -3*X2Fix(π/4)=3*0.C910 hex
  28474.  
  28475. æKY Frac2Fix
  28476. æFc FixMath.h
  28477. æT Function
  28478. æTN A842
  28479. æD pascal Fixed Frac2Fix(Fract x)
  28480.     = 0xA842; 
  28481. æDT Fixed myVariable = Frac2Fix((Fract) x);
  28482. æRI IV-65
  28483. æC 
  28484. Long2Fix, Fix2Long, Fix2Frac, and Frac2Fix convert between fixed-point types.
  28485.  
  28486. Examples
  28487.  
  28488. Examples of the use of these fixed-point functions are provided below; all numbers
  28489. are decimal unless otherwise noted.
  28490.  
  28491. Function                                 Result      Comment
  28492. FixDiv    (X2Fix(1.95), X2Fix(1.30))     $00018000    1.5 = 01.10 bin
  28493. FracDiv   (X2Frac(1.95), X2Frac(1.30))   $60000000    1.5 = 01.10 bin
  28494. FracMul   (X2Frac(1.50), X2Frac(1.30))   $7CCCCCCD    1.95 rounded
  28495. FracSqrt  (X2Frac(1.96))                 $5999999A    1.4 rounded
  28496. FracSin   (X2Fix(3.1416015625))          $00000000    0
  28497. FracCos   (X2Fix(3.1416015625))          $C0000000   -1
  28498. Fix2Long  (X2Fix(1.75))                  $00000002    2
  28499. Fix2Frac  (X2Fix(1.75))                  $70000000    1.75 = 01.11 bin
  28500. Frac2Fix  (X2Frac(1.75))                 $0001C000    1.75 = 01.11 bin
  28501. FixATan2  (X2Fix(1.00), X2Fix(1.00))     $0000C910    0.C910 hex = X2Fix (π/4)
  28502. FixDiv    (X2Fix(-1.95), X2Fix(1.30))    $FFFE8000   -1.5
  28503. FracDiv   (X2Frac(-1.95), X2Frac(1.30))  $A0000000   -1.5
  28504. FracMul   (X2Frac(-1.50), X2Frac(1.30))  $83333333   -1.95 rounded
  28505. FracSin   (X2Fix(-3.1416015625))         $00000000    0
  28506. FracCos   (X2Fix(-3.1416015625))         $C0000000   -1
  28507. Fix2Long  (X2Fix(-1.75))                 $FFFFFFFE   -2
  28508. Fix2Frac  (X2Fix(-1.75))                 $90000000   -1.75
  28509. Frac2Fix  (X2Frac(-1.75))                $FFFE4000   -1.75
  28510. FixATan2  (X2Fix(-1.00), X2Fix(-1.00))   $FFFDA4D0   -3*X2Fix(π/4)=3*0.C910 hex
  28511.  
  28512. æKY Frac2X
  28513. æFc FixMath.h
  28514. æT Function
  28515. æD pascal extended Frac2X(Fract x); 
  28516. æDT extended myVariable = Frac2X((Fract) x);
  28517. æRI IV-65
  28518. æC 
  28519. Fix2X, X2Fix, Frac2X, and X2Frac convert between Fixed and Fract and the Extended
  28520. floating-point type. These functions do not set floating-point exception flags.
  28521.  
  28522. Examples
  28523.  
  28524. Examples of the use of these fixed-point functions are provided below; all numbers
  28525. are decimal unless otherwise noted.
  28526.  
  28527. Function                                 Result      Comment
  28528. FixDiv    (X2Fix(1.95), X2Fix(1.30))     $00018000    1.5 = 01.10 bin
  28529. FracDiv   (X2Frac(1.95), X2Frac(1.30))   $60000000    1.5 = 01.10 bin
  28530. FracMul   (X2Frac(1.50), X2Frac(1.30))   $7CCCCCCD    1.95 rounded
  28531. FracSqrt  (X2Frac(1.96))                 $5999999A    1.4 rounded
  28532. FracSin   (X2Fix(3.1416015625))          $00000000    0
  28533. FracCos   (X2Fix(3.1416015625))          $C0000000   -1
  28534. Fix2Long  (X2Fix(1.75))                  $00000002    2
  28535. Fix2Frac  (X2Fix(1.75))                  $70000000    1.75 = 01.11 bin
  28536. Frac2Fix  (X2Frac(1.75))                 $0001C000    1.75 = 01.11 bin
  28537. FixATan2  (X2Fix(1.00), X2Fix(1.00))     $0000C910    0.C910 hex = X2Fix (π/4)
  28538. FixDiv    (X2Fix(-1.95), X2Fix(1.30))    $FFFE8000   -1.5
  28539. FracDiv   (X2Frac(-1.95), X2Frac(1.30))  $A0000000   -1.5
  28540. FracMul   (X2Frac(-1.50), X2Frac(1.30))  $83333333   -1.95 rounded
  28541. FracSin   (X2Fix(-3.1416015625))         $00000000    0
  28542. FracCos   (X2Fix(-3.1416015625))         $C0000000   -1
  28543. Fix2Long  (X2Fix(-1.75))                 $FFFFFFFE   -2
  28544. Fix2Frac  (X2Fix(-1.75))                 $90000000   -1.75
  28545. Frac2Fix  (X2Frac(-1.75))                $FFFE4000   -1.75
  28546. FixATan2  (X2Fix(-1.00), X2Fix(-1.00))   $FFFDA4D0   -3*X2Fix(π/4)=3*0.C910 hex
  28547.  
  28548. æKY Fix2X
  28549. æFc FixMath.h
  28550. æT Function
  28551. æD pascal extended Fix2X(Fixed x); 
  28552. æDT extended myVariable = Fix2X((Fixed) x);
  28553. æRI IV-65
  28554. æC 
  28555. Fix2X, X2Fix, Frac2X, and X2Frac convert between Fixed and Fract and the Extended
  28556. floating-point type. These functions do not set floating-point exception flags.
  28557.  
  28558. Examples
  28559.  
  28560. Examples of the use of these fixed-point functions are provided below; all numbers
  28561. are decimal unless otherwise noted.
  28562.  
  28563. Function                                 Result      Comment
  28564. FixDiv    (X2Fix(1.95), X2Fix(1.30))     $00018000    1.5 = 01.10 bin
  28565. FracDiv   (X2Frac(1.95), X2Frac(1.30))   $60000000    1.5 = 01.10 bin
  28566. FracMul   (X2Frac(1.50), X2Frac(1.30))   $7CCCCCCD    1.95 rounded
  28567. FracSqrt  (X2Frac(1.96))                 $5999999A    1.4 rounded
  28568. FracSin   (X2Fix(3.1416015625))          $00000000    0
  28569. FracCos   (X2Fix(3.1416015625))          $C0000000   -1
  28570. Fix2Long  (X2Fix(1.75))                  $00000002    2
  28571. Fix2Frac  (X2Fix(1.75))                  $70000000    1.75 = 01.11 bin
  28572. Frac2Fix  (X2Frac(1.75))                 $0001C000    1.75 = 01.11 bin
  28573. FixATan2  (X2Fix(1.00), X2Fix(1.00))     $0000C910    0.C910 hex = X2Fix (π/4)
  28574. FixDiv    (X2Fix(-1.95), X2Fix(1.30))    $FFFE8000   -1.5
  28575. FracDiv   (X2Frac(-1.95), X2Frac(1.30))  $A0000000   -1.5
  28576. FracMul   (X2Frac(-1.50), X2Frac(1.30))  $83333333   -1.95 rounded
  28577. FracSin   (X2Fix(-3.1416015625))         $00000000    0
  28578. FracCos   (X2Fix(-3.1416015625))         $C0000000   -1
  28579. Fix2Long  (X2Fix(-1.75))                 $FFFFFFFE   -2
  28580. Fix2Frac  (X2Fix(-1.75))                 $90000000   -1.75
  28581. Frac2Fix  (X2Frac(-1.75))                $FFFE4000   -1.75
  28582. FixATan2  (X2Fix(-1.00), X2Fix(-1.00))   $FFFDA4D0   -3*X2Fix(π/4)=3*0.C910 hex
  28583.  
  28584. æKY X2Fix
  28585. æFc FixMath.h
  28586. æT Function
  28587. æD pascal Fixed X2Fix(extended x); 
  28588. æDT Fixed myVariable = X2Fix((extended) x);
  28589. æRI IV-65
  28590. æC 
  28591. Fix2X, X2Fix, Frac2X, and X2Frac convert between Fixed and Fract and the Extended
  28592. floating-point type. These functions do not set floating-point exception flags.
  28593.  
  28594. Examples
  28595.  
  28596. Examples of the use of these fixed-point functions are provided below; all numbers
  28597. are decimal unless otherwise noted.
  28598.  
  28599. Function                                 Result      Comment
  28600. FixDiv    (X2Fix(1.95), X2Fix(1.30))     $00018000    1.5 = 01.10 bin
  28601. FracDiv   (X2Frac(1.95), X2Frac(1.30))   $60000000    1.5 = 01.10 bin
  28602. FracMul   (X2Frac(1.50), X2Frac(1.30))   $7CCCCCCD    1.95 rounded
  28603. FracSqrt  (X2Frac(1.96))                 $5999999A    1.4 rounded
  28604. FracSin   (X2Fix(3.1416015625))          $00000000    0
  28605. FracCos   (X2Fix(3.1416015625))          $C0000000   -1
  28606. Fix2Long  (X2Fix(1.75))                  $00000002    2
  28607. Fix2Frac  (X2Fix(1.75))                  $70000000    1.75 = 01.11 bin
  28608. Frac2Fix  (X2Frac(1.75))                 $0001C000    1.75 = 01.11 bin
  28609. FixATan2  (X2Fix(1.00), X2Fix(1.00))     $0000C910    0.C910 hex = X2Fix (π/4)
  28610. FixDiv    (X2Fix(-1.95), X2Fix(1.30))    $FFFE8000   -1.5
  28611. FracDiv   (X2Frac(-1.95), X2Frac(1.30))  $A0000000   -1.5
  28612. FracMul   (X2Frac(-1.50), X2Frac(1.30))  $83333333   -1.95 rounded
  28613. FracSin   (X2Fix(-3.1416015625))         $00000000    0
  28614. FracCos   (X2Fix(-3.1416015625))         $C0000000   -1
  28615. Fix2Long  (X2Fix(-1.75))                 $FFFFFFFE   -2
  28616. Fix2Frac  (X2Fix(-1.75))                 $90000000   -1.75
  28617. Frac2Fix  (X2Frac(-1.75))                $FFFE4000   -1.75
  28618. FixATan2  (X2Fix(-1.00), X2Fix(-1.00))   $FFFDA4D0   -3*X2Fix(π/4)=3*0.C910 hex
  28619.  
  28620. æKY X2Frac
  28621. æFc FixMath.h
  28622. æT Function
  28623. æD pascal Fract X2Frac(extended x); 
  28624. æDT Fract myVariable = X2Frac((extended) x);
  28625. æRI IV-65
  28626. æC 
  28627. Fix2X, X2Fix, Frac2X, and X2Frac convert between Fixed and Fract and the Extended
  28628. floating-point type. These functions do not set floating-point exception flags.
  28629.  
  28630. Examples
  28631.  
  28632. Examples of the use of these fixed-point functions are provided below; all numbers
  28633. are decimal unless otherwise noted.
  28634.  
  28635. Function                                 Result      Comment
  28636. FixDiv    (X2Fix(1.95), X2Fix(1.30))     $00018000    1.5 = 01.10 bin
  28637. FracDiv   (X2Frac(1.95), X2Frac(1.30))   $60000000    1.5 = 01.10 bin
  28638. FracMul   (X2Frac(1.50), X2Frac(1.30))   $7CCCCCCD    1.95 rounded
  28639. FracSqrt  (X2Frac(1.96))                 $5999999A    1.4 rounded
  28640. FracSin   (X2Fix(3.1416015625))          $00000000    0
  28641. FracCos   (X2Fix(3.1416015625))          $C0000000   -1
  28642. Fix2Long  (X2Fix(1.75))                  $00000002    2
  28643. Fix2Frac  (X2Fix(1.75))                  $70000000    1.75 = 01.11 bin
  28644. Frac2Fix  (X2Frac(1.75))                 $0001C000    1.75 = 01.11 bin
  28645. FixATan2  (X2Fix(1.00), X2Fix(1.00))     $0000C910    0.C910 hex = X2Fix (π/4)
  28646. FixDiv    (X2Fix(-1.95), X2Fix(1.30))    $FFFE8000   -1.5
  28647. FracDiv   (X2Frac(-1.95), X2Frac(1.30))  $A0000000   -1.5
  28648. FracMul   (X2Frac(-1.50), X2Frac(1.30))  $83333333   -1.95 rounded
  28649. FracSin   (X2Fix(-3.1416015625))         $00000000    0
  28650. FracCos   (X2Fix(-3.1416015625))         $C0000000   -1
  28651. Fix2Long  (X2Fix(-1.75))                 $FFFFFFFE   -2
  28652. Fix2Frac  (X2Fix(-1.75))                 $90000000   -1.75
  28653. Frac2Fix  (X2Frac(-1.75))                $FFFE4000   -1.75
  28654. FixATan2  (X2Fix(-1.00), X2Fix(-1.00))   $FFFDA4D0   -3*X2Fix(π/4)=3*0.C910 hex
  28655.  
  28656. æKY FracMul
  28657. æFc FixMath.h
  28658. æT Function
  28659. æTN A84A
  28660. æD pascal Fract FracMul(Fract x,Fract y)
  28661.     = 0xA84A; 
  28662. æDT Fract myVariable = FracMul((Fract) x,(Fract) y);
  28663. æRI IV-64
  28664. æC 
  28665. FracMul returns x * y. Note that FracMul effects “type * Fract --> type”:
  28666.  
  28667.   Fract    *    Fract    -->    Fract
  28668.   LONGINT  *    Fract    -->    LONGINT
  28669.   Fract    *    LONGINT  -->    LONGINT
  28670.   Fixed    *    Fract    -->    Fixed
  28671.   Fract    *    Fixed    -->    Fixed
  28672.  
  28673. æKY FixDiv
  28674. æFc FixMath.h
  28675. æT Function
  28676. æTN A84D
  28677. æD pascal Fixed FixDiv(Fixed x,Fixed y)
  28678.     = 0xA84D; 
  28679. æDT Fixed myVariable = FixDiv((Fixed) x,(Fixed) y);
  28680. æRI IV-64
  28681. æC 
  28682. FixDiv returns x / y. Note that FixDiv effects “type / type --> Fixed” and
  28683. “type / Fixed --> type”:
  28684.  
  28685.   Fixed    /    Fixed    -->    Fixed
  28686.   LONGINT  /    LONGINT  -->    Fixed
  28687.   Fract    /    Fract    -->    Fixed
  28688.   LONGINT  /    Fixed    -->    LONGINT
  28689.   Fract    /    Fixed    -->    Fract
  28690.  
  28691. æKY FracDiv
  28692. æFc FixMath.h
  28693. æT Function
  28694. æTN A84B
  28695. æD pascal Fract FracDiv(Fract x,Fract y)
  28696.     = 0xA84B; 
  28697. æDT Fract myVariable = FracDiv((Fract) x,(Fract) y);
  28698. æRI IV-64
  28699. æC 
  28700. FracDiv returns x / y. Note that FracDiv effects “type / type --> Fract” and
  28701. “type / Fract --> type”:
  28702.  
  28703.   Fract    /    Fract    -->    Fract
  28704.   LONGINT  /    LONGINT  -->    Fract
  28705.   Fixed    /    Fixed    -->    Fract
  28706.   LONGINT  /    Fract    -->    LONGINT
  28707.   Fixed    /    Fract    -->    Fixed
  28708.  
  28709. æKY FracSqrt
  28710. æFc FixMath.h
  28711. æT Function
  28712. æTN A849
  28713. æD pascal Fract FracSqrt(Fract x)
  28714.     = 0xA849; 
  28715. æDT Fract myVariable = FracSqrt((Fract) x);
  28716. æRI IV-64
  28717. æC  
  28718. FracSqrt returns the square root of x, with x interpreted as unsigned in the range 0
  28719. through 4–(2–30), inclusive:  That is, bit 15 in Figure 1 has weight 2 rather than
  28720. –2. The result, too, is unsigned in the range 0 through 2, inclusive.
  28721.  
  28722. æKY FracSin
  28723. æFc FixMath.h
  28724. æT Function
  28725. æTN A848
  28726. æD pascal Fract FracSin(Fixed x)
  28727.     = 0xA848; 
  28728. æDT Fract myVariable = FracSin((Fixed) x);
  28729. æRI IV-64
  28730. æC 
  28731. FracCos and FracSin return the cosine and sine of their radian arguments, respectively.
  28732. The hexadecimal value 0.C910 (which is FixATan2(1,1)) is the approximation to π/4
  28733. used for argument reduction. Thus, FracCos and FracSin are nearly periodic, but with
  28734. period 2*P instead of 2*π, where P=3.1416015625 and π, of course, is 3.14159265....
  28735.  
  28736. æKY FracCos
  28737. æFc FixMath.h
  28738. æT Function
  28739. æTN A847
  28740. æD pascal Fract FracCos(Fixed x)
  28741.     = 0xA847; 
  28742. æDT Fract myVariable = FracCos((Fixed) x);
  28743. æRI IV-64
  28744. æC 
  28745. FracCos and FracSin return the cosine and sine of their radian arguments, respectively.
  28746. The hexadecimal value 0.C910 (which is FixATan2(1,1)) is the approximation to π/4
  28747. used for argument reduction. Thus, FracCos and FracSin are nearly periodic, but with
  28748. period 2*P instead of 2*π, where P=3.1416015625 and π, of course, is 3.14159265....
  28749.  
  28750.  
  28751. æKY Float.h
  28752. æFc Float.h
  28753. æD                            Synopsis
  28754.  
  28755. #define DBL_DIG          15
  28756. #define DBL_EPSILO       (scalb(-52,1.0))
  28757. #define DBL_MANT_DIG     53
  28758. #define DBL_MAX          (nextdouble(inf(),0.0))
  28759. #define DBL_MAX_10_EXP   308
  28760. #define DBL_MAX_EXP      1024
  28761. #define DBL_MI           (scalb(DBL_MIN_EXP-1,1.0))
  28762. #define DBL_MIN_10_EXP   (-307)
  28763. #define DBL_MIN_EXP      (-1021)
  28764. #define FLT_DIG          7
  28765. #define FLT_EPSILO       (scalb(-23,1.0))
  28766. #define FLT_MANT_DIG     24
  28767. #define FLT_MAX          (nextfloat(inf(),0.0))
  28768. #define FLT_MAX_10_EXP   38
  28769. #define FLT_MAX_EXP      128
  28770. #define FLT_MI           (scalb(FLT_MIN_EXP-1,1.0))
  28771. #define FLT_MIN_10_EXP   (-37)
  28772. #define FLT_MIN_EXP      (-125)
  28773. #define FLT_RADIX        2
  28774. #define FLT_ROUNDS       ((getround()+1) % 4)
  28775. #define LDBL_DIG         19
  28776. #define LDBL_EPSILO      (scalb(-63,1.0))
  28777. #define LDBL_MANT_DIG    64
  28778. #define LDBL_MAX         (nextextended(inf(),0.0))
  28779. #define LDBL_MAX_10_EXP  4932
  28780. #define LDBL_MAX_EXP     16384
  28781. #define LDBL_MI          (scalb(LDBL_MIN_EXP-1,1.0))
  28782. #define LDBL_MIN_10_EXP  (-4931)
  28783. #define LDBL_MIN_EXP     (-16382)
  28784.  
  28785.  
  28786. æC                           Description
  28787.  
  28788. The header <Float.h> specifies the characteristics of floating 
  28789. types float, double, and long double. The functions scalb, 
  28790. nextfloat, nextround, and nextextended, used in the macros 
  28791. above, are declared in <SANE.h>.
  28792.  
  28793. See also
  28794. Apple Numerics Manual, 2nd edition
  28795.  
  28796.  
  28797. æKY Folders.h
  28798. æKL FindFolder
  28799.  
  28800. kAppleMenuFolderType
  28801. kControlPanelFolderType
  28802. kCreateFolder
  28803. kDesktopFolderType
  28804. kDontCreateFolder
  28805. kExtensionFolderType
  28806. kOnSystemDisk
  28807. kPreferencesFolderType
  28808. kSpoolFolderType
  28809. kStartupFolderType
  28810. kSystemFolderType
  28811. kTemporaryFolderType
  28812. kTrashFolderType
  28813. kWhereToEmptyTrashFolderType
  28814.  
  28815. æKY kOnSystemDisk
  28816. æFc Folders.h
  28817. æT #define
  28818. æD #define kOnSystemDisk 0x8000
  28819. æC 
  28820.  
  28821. æKY kCreateFolder
  28822. æFc Folders.h
  28823. æT #define
  28824. æD #define kCreateFolder TRUE
  28825. æC 
  28826.  
  28827. æKY kDontCreateFolder
  28828. æFc Folders.h
  28829. æT #define
  28830. æD #define kDontCreateFolder FALSE
  28831. æC 
  28832.  
  28833. æKY kSystemFolderType
  28834. æFc Folders.h
  28835. æT #define
  28836. æD #define kSystemFolderType 'macs' /*the system folder*/
  28837. æC 
  28838.  
  28839. æKY kDesktopFolderType
  28840. æFc Folders.h
  28841. æT #define
  28842. æD #define kDesktopFolderType 'desk' /*the desktop folder; objects in this folder show on the desk top.*/
  28843. æC 
  28844.  
  28845. æKY kTrashFolderType
  28846. æFc Folders.h
  28847. æT #define
  28848. æD #define kTrashFolderType 'trsh' /*the trash folder; objects in this folder show up in the trash*/
  28849. æC 
  28850.  
  28851. æKY kWhereToEmptyTrashFolderType
  28852. æFc Folders.h
  28853. æT #define
  28854. æD #define kWhereToEmptyTrashFolderType 'empt' /*the "empty trash" folder; Finder starts empty from here down*/
  28855. æC 
  28856.  
  28857. æKY kSpoolFolderType
  28858. æFc Folders.h
  28859. æT #define
  28860. æD #define kSpoolFolderType 'spoo' /*spool files go here (from the print drivers to the despooler*/
  28861. æC 
  28862.  
  28863. æKY kStartupFolderType
  28864. æFc Folders.h
  28865. æT #define
  28866. æD #define kStartupFolderType 'strt' /*Finder objects (applications, documents, DAs, aliases, to...) to open at startup go here*/
  28867. æC 
  28868.  
  28869. æKY kAppleMenuFolderType
  28870. æFc Folders.h
  28871. æT #define
  28872. æD #define kAppleMenuFolderType 'amnu' /*Finder objects to put into the Apple menu go here*/
  28873. æC 
  28874.  
  28875. æKY kControlPanelFolderType
  28876. æFc Folders.h
  28877. æT #define
  28878. æD #define kControlPanelFolderType 'ctrl' /*Control Panels go here (may contain INITs)*/
  28879. æC 
  28880.  
  28881. æKY kExtensionFolderType
  28882. æFc Folders.h
  28883. æT #define
  28884. æD #define kExtensionFolderType 'extn' /*Finder extensions go here*/
  28885. æC 
  28886.  
  28887. æKY kPreferencesFolderType
  28888. æFc Folders.h
  28889. æT #define
  28890. æD #define kPreferencesFolderType 'pref' /*preferences for applications go here*/
  28891. æC 
  28892.  
  28893. æKY kTemporaryFolderType
  28894. æFc Folders.h
  28895. æT #define
  28896. æD #define kTemporaryFolderType 'temp' /*temporary files go here (deleted periodically, but don't rely on it.)*/
  28897. æC 
  28898.  
  28899. æKY FindFolder
  28900. æFc Folders.h
  28901. æT Function
  28902. æD pascal OSErr FindFolder(short vRefNum,OSType folderType,Boolean  createFolder,
  28903.     short *foundVRefNum,long *foundDirID)
  28904.     = {0x7000,0xA823}; 
  28905. æDT OSErr myVariable = FindFolder((short) vRefNum,(OSType) folderType,(Boolean)  createFolder,(
  28906.     short) * foundVRefNum,(long *) foundDirID);
  28907. æC 
  28908. You can call the FindFolder function to get the path information so that you can
  28909. access special folders. You pass FindFolder a target volume and a constant that
  28910. tells it which special folder you are interested in. FindFolder returns a volume
  28911. reference number and a directory ID. If the specified folder does not exist,
  28912. FindFolder can create it and return the new directory ID.
  28913.  
  28914. The Finder identifies the folder types and their names in a resource of type 
  28915. 'fld#'. Table 8-2 lists the folder types in version 7.0, their resource types,
  28916. and the constants that represent them.
  28917.  
  28918. Table 8-2.  Special folders
  28919.  
  28920. Folder                Type    Constant
  28921.  
  28922. System Folder         'macs'  kSystemFolderType
  28923. Extensions folder     'extn'  kExtensionFolderType
  28924. Preferences folder    'pref'  kPreferencesFolderType
  28925. Apple Menu Folder     'amnu'  kAppleMenuFolderType
  28926. Startup Folder        'strt'  kStartupFolderType
  28927. Print Monitor Folder  'spoo'  kSpoolFolderType
  28928. Temporary folder      'temp'  kTemporaryFolderType
  28929. Desktop folder        'desk'  kDesktopFolderType
  28930. Single-user
  28931.     trash folder      'trsh'  kTrashFolderType
  28932. Shared trash folder   'empt'  kSharedTrashFolderType
  28933.  
  28934. In calls to FindFolder, you can use these three constants:
  28935.  
  28936. CONST
  28937. kOnSystemDisk = $8000;
  28938. kCreateFolder = TRUE;
  28939. kDontCreateFolder = FALSE;
  28940.  
  28941. Call the FindFolder function to get a volume and directory ID for a special
  28942. folder.
  28943.  
  28944. The FindFolder function returns the volume reference number and directory ID of
  28945. a specified special folder on a specified volume. You specify a volume reference
  28946. number (or the constant kOnSystemDisk for the boot disk) in the vRefNum
  28947. parameter. You specify the folder type in the folderType parameter, using one of
  28948. the constants listed in Table 8-2. The createFolder parameter tells FindFolder
  28949. whether or not to create a folder if it does not already exist. FindFolder puts
  28950. the results in foundVRefNum and foundDirID.
  28951.  
  28952. Result codes
  28953. fnfErr  -43     Type not found in 'fld# resource;
  28954.                 Folder not found and createFolder flag false
  28955. dupFNErr  -48   File found instead of folder
  28956.  
  28957.  
  28958. æKY Fonts.h
  28959. æKL FMSwapFont
  28960. FontMetrics
  28961. getfnum
  28962. GetFNum
  28963. getfontname
  28964. GetFontName
  28965. InitFonts
  28966. RealFont
  28967. SetFontLock
  28968. SetFractEnable
  28969. SetFScaleDisable
  28970.  
  28971. appleMark
  28972. applFont
  28973. AsscEntry
  28974. athens
  28975. cairo
  28976. checkMark
  28977. commandMark
  28978. courier
  28979. diamondMark
  28980. FamRec
  28981. fixedFont
  28982. FMetricRec
  28983. FMInput
  28984. FMOutPtr
  28985. FMOutput
  28986. FontAssoc
  28987. FontRec
  28988. fontWid
  28989. fxdFntH
  28990. fxdFntHW
  28991. fxdFntW
  28992. geneva
  28993. helvetica
  28994. KernEntry
  28995. KernPair
  28996. KernTable
  28997. london
  28998. losAngeles
  28999. mobile
  29000. monaco
  29001. NameTable
  29002. newYork
  29003. propFont
  29004. prpFntH
  29005. prpFntHW
  29006. prpFntW
  29007. sanFran
  29008. StyleTable
  29009. symbol
  29010. systemFont
  29011. times
  29012. toronto
  29013. venice
  29014. WidEntry
  29015. WidTable
  29016. WidthTable
  29017.  
  29018. æKY systemFont
  29019. æFc Fonts.h
  29020. æT #define
  29021. æD #define systemFont 0
  29022. æC 
  29023. _______________________________________________________________________________
  29024.  
  29025. »FONT NUMBERS
  29026. _______________________________________________________________________________
  29027.  
  29028. Note:  The information on Font Numbers described in the following
  29029.        paragraphs was originally documented in Inside Macintosh, Volume I.
  29030.  
  29031. The Font Manager includes the following font numbers for identifying system-defined
  29032. fonts:
  29033.  
  29034. CONST  systemFont  = 0;    {system font}
  29035.        applFont    = 1;    {application font}
  29036.        newYork     = 2;
  29037.        geneva      = 3;
  29038.        monaco      = 4;
  29039.        venice      = 5;
  29040.        london      = 6;
  29041.        athens      = 7;
  29042.        sanFran     = 8;
  29043.        toronto     = 9;
  29044.        cairo       = 11;
  29045.        losAngeles  = 12;
  29046.        times       = 20;
  29047.        helvetica   = 21;
  29048.        courier     = 22;
  29049.        symbol      = 23;
  29050.        taliesin    = 24;
  29051.  
  29052. The system font is so called because it’s the font used by the system (for drawing
  29053. menu titles and commands in menus, for example). The name of the system font is
  29054. Chicago. The size of text drawn by the system in this font is fixed at 12 points
  29055. (called the system font size).
  29056.  
  29057. The application font is the font your application will use unless you specify otherwise.
  29058. Unlike the system font, the application font isn’t a separate font, but is essentially
  29059. a reference to another font—Geneva, by default. (The application font number is
  29060. determined by a value that you can set in parameter RAM; see the Operating System
  29061. Utilities chapter for more information.)
  29062.  
  29063. Assembly-language note:  You can get the application font number
  29064.                          from the global variable ApFontID.
  29065.  
  29066. æKY applFont
  29067. æFc Fonts.h
  29068. æT #define
  29069. æD #define applFont 1
  29070. æC 
  29071.  
  29072. æKY newYork
  29073. æFc Fonts.h
  29074. æT #define
  29075. æD #define newYork 2
  29076. æC 
  29077.  
  29078. æKY geneva
  29079. æFc Fonts.h
  29080. æT #define
  29081. æD #define geneva 3
  29082. æC 
  29083.  
  29084. æKY monaco
  29085. æFc Fonts.h
  29086. æT #define
  29087. æD #define monaco 4
  29088. æC 
  29089.  
  29090. æKY venice
  29091. æFc Fonts.h
  29092. æT #define
  29093. æD #define venice 5
  29094. æC 
  29095.  
  29096. æKY london
  29097. æFc Fonts.h
  29098. æT #define
  29099. æD #define london 6
  29100. æC 
  29101.  
  29102. æKY athens
  29103. æFc Fonts.h
  29104. æT #define
  29105. æD #define athens 7
  29106. æC 
  29107.  
  29108. æKY sanFran
  29109. æFc Fonts.h
  29110. æT #define
  29111. æD #define sanFran 8
  29112. æC 
  29113.  
  29114. æKY toronto
  29115. æFc Fonts.h
  29116. æT #define
  29117. æD #define toronto 9
  29118. æC 
  29119.  
  29120. æKY cairo
  29121. æFc Fonts.h
  29122. æT #define
  29123. æD #define cairo 11
  29124. æC 
  29125.  
  29126. æKY losAngeles
  29127. æFc Fonts.h
  29128. æT #define
  29129. æD #define losAngeles 12
  29130. æC 
  29131.  
  29132. æKY times
  29133. æFc Fonts.h
  29134. æT #define
  29135. æD #define times 20
  29136. æC 
  29137.  
  29138. æKY helvetica
  29139. æFc Fonts.h
  29140. æT #define
  29141. æD #define helvetica 21
  29142. æC 
  29143.  
  29144. æKY courier
  29145. æFc Fonts.h
  29146. æT #define
  29147. æD #define courier 22
  29148. æC 
  29149.  
  29150. æKY symbol
  29151. æFc Fonts.h
  29152. æT #define
  29153. æD #define symbol 23
  29154. æC 
  29155.  
  29156. æKY mobile
  29157. æFc Fonts.h
  29158. æT #define
  29159. æD #define mobile 24
  29160. æC 
  29161.  
  29162. æKY commandMark
  29163. æFc Fonts.h
  29164. æT #define
  29165. æD #define commandMark 17
  29166. æC 
  29167. _______________________________________________________________________________
  29168. »CHARACTERS IN A FONT
  29169. _______________________________________________________________________________
  29170.  
  29171. Note:  The information on the Characters In A Font described in the following
  29172.        paragraphs was originally documented in Inside Macintosh, Volume I.
  29173.  
  29174. A font can consist of up to 255 distinct characters; not all characters need to be
  29175. defined in a single font. Figure 20 shows the standard printing characters on the
  29176. Macintosh and their ASCII codes (for example, the ASCII code for “A” is 41 hexadecimal,
  29177. or 65 decimal).
  29178.  
  29179. Note:  Codes $00 through $1F and code $7F are normally nonprinting
  29180.        characters (see the Toolbox Event Manager chapter for details).
  29181.  
  29182. The special characters in the system font with codes $11 through $14 can’t normally
  29183. be typed from the keyboard or keypad. The Font Manager defines constants for these
  29184. characters:
  29185.  
  29186. CONST  commandMark  = $11;    {Command key symbol}
  29187.        checkMark    = $12;    {check mark}
  29188.        diamondMark  = $13;    {diamond symbol}
  29189.        appleMark    = $14;    {apple symbol}
  29190.  
  29191. In addition to its maximum of 255 characters, every font contains a missing symbol
  29192. that’s drawn in case of a request to draw a character that’s missing from the font.
  29193.  
  29194. •••Refer to Figure 20.•••
  29195.  
  29196. Figure 20–Font Characters
  29197.  
  29198. æKY checkMark
  29199. æFc Fonts.h
  29200. æT #define
  29201. æD #define checkMark 18
  29202. æC 
  29203.  
  29204. æKY diamondMark
  29205. æFc Fonts.h
  29206. æT #define
  29207. æD #define diamondMark 19
  29208. æC 
  29209.  
  29210. æKY appleMark
  29211. æFc Fonts.h
  29212. æT #define
  29213. æD #define appleMark 20
  29214. æC 
  29215.  
  29216. æKY propFont
  29217. æFc Fonts.h
  29218. æT #define
  29219. æD #define propFont 36864
  29220. æC 
  29221.  
  29222. æKY prpFntH
  29223. æFc Fonts.h
  29224. æT #define
  29225. æD #define prpFntH 36865
  29226. æC 
  29227.  
  29228. æKY prpFntW
  29229. æFc Fonts.h
  29230. æT #define
  29231. æD #define prpFntW 36866
  29232. æC 
  29233.  
  29234. æKY prpFntHW
  29235. æFc Fonts.h
  29236. æT #define
  29237. æD #define prpFntHW 36867
  29238. æC 
  29239.  
  29240. æKY fixedFont
  29241. æFc Fonts.h
  29242. æT #define
  29243. æD #define fixedFont 45056
  29244. æC 
  29245.  
  29246. æKY fxdFntH
  29247. æFc Fonts.h
  29248. æT #define
  29249. æD #define fxdFntH 45057
  29250. æC 
  29251.  
  29252. æKY fxdFntW
  29253. æFc Fonts.h
  29254. æT #define
  29255. æD #define fxdFntW 45058
  29256. æC 
  29257.  
  29258. æKY fxdFntHW
  29259. æFc Fonts.h
  29260. æT #define
  29261. æD #define fxdFntHW 45059
  29262. æC 
  29263.  
  29264. æKY fontWid
  29265. æFc Fonts.h
  29266. æT #define
  29267. æD #define fontWid 44208
  29268. æC 
  29269.  
  29270. æKY FMInput
  29271. æFc Fonts.h
  29272. æT struct
  29273. æD struct FMInput {
  29274.     short family;
  29275.     short size;
  29276.     Style face;
  29277.     Boolean needBits;
  29278.     short device;
  29279.     Point numer;
  29280.     Point denom;
  29281. };
  29282.  
  29283. typedef struct FMInput FMInput;
  29284. æC 
  29285. ______________________________________________________________________________
  29286.  
  29287. »COMMUNICATION BETWEEN QUICKDRAW AND THE FONT MANAGER
  29288. _______________________________________________________________________________
  29289.  
  29290. This section describes the data structures that allow QuickDraw and the Font Manager
  29291. to exchange information. It also discusses the communication that may occur between
  29292. the Font Manager and the driver of the device on which the characters are being drawn
  29293. or printed. You can skip this section if you want to change fonts, character style,
  29294. and font sizes by calling QuickDraw and aren’t interested in the lower-level data
  29295. structures and routines of the Font Manager. To understand this section fully, you’ll
  29296. have to be familiar with device drivers and the Device Manager.
  29297.  
  29298. Whenever you call a QuickDraw routine that does anything with text, QuickDraw requests
  29299. information from the Font Manager about the characters. The Font Manager performs any
  29300. necessary calculations and returns the requested information to QuickDraw. As illustrated
  29301. in Figure 21, this information exchange occurs via two data structures, a font input
  29302. record (type FMInput) and a font output record (type FMOutput).
  29303.  
  29304. First, QuickDraw passes the Font Manager a font input record:
  29305.  
  29306. TYPE FMInput = PACKED RECORD
  29307.                  family:    INTEGER;  {font number}
  29308.                  size:      INTEGER;  {font size}
  29309.                  face:      Style;    {character style}
  29310.                  needBits:  BOOLEAN;  {TRUE if drawing}
  29311.                  device:    INTEGER;  {device-specific information}
  29312.                  numer:     Point;    {numerators of scaling factors}
  29313.                  denom:     Point     {denominators of scaling factors}
  29314.                END;
  29315.  
  29316. The first three fields contain the font number, size, and character style that QuickDraw
  29317. wants to use.
  29318.  
  29319. The needBits field indicates whether the characters actually will be drawn or not. If
  29320. the characters are being drawn, all of the information describing the font, including
  29321. the bit image comprising the characters, will be read into memory. If the characters
  29322. aren’t being drawn and there’s a resource consisting of only the character widths and
  29323. general font information, that resource will be read instead.
  29324.  
  29325. The high-order byte of the device field contains a device driver reference number.
  29326. From the driver reference number, the Font Manager can determine the optimum stylistic
  29327. variations on the font to produce the highest-quality printing or drawing available
  29328. on a device (as explained below). The low-order byte of the device field is ignored
  29329. by the Font Manager but may contain information used by the device driver.
  29330.  
  29331. •••Refer to Figure 21.•••
  29332.  
  29333. Figure 21–Communication About Fonts
  29334.  
  29335. The numer and denom fields contain the scaling factors to be used; numer.v divided by
  29336. denom.v gives the vertical scaling, and numer.h divided by denom.h gives the horizontal
  29337. scaling.
  29338.  
  29339. The Font Manager takes the font input record and asks the Resource Manager for the
  29340. font. If the requested size isn’t available, the Font Manager scales another size to
  29341. match (as described under “Font Scaling”).
  29342.  
  29343. Then the Font Manager gets the font characterization table via the device field. If
  29344. the high-order byte of the device field is 0, the Font Manager gets the screen’s font
  29345. characterization table (which is stored in the Font Manager). If the high-order byte
  29346. of the device field is nonzero, the Font Manager calls the status routine of the
  29347. device driver having that reference number, and the status routine returns a font
  29348. characterization table. The status routine may use the value of the low-order byte of
  29349. the device field to determine the font characterization table it should return.
  29350.  
  29351. Note:  If you want to make your own calls to the device driver’s Status
  29352.        function, the reference number must be the driver reference number
  29353.        from the font input record’s device field, csCode must be 8, csParam
  29354.        must be a pointer to where the device driver should put the font
  29355.        characterization table, and csParam+4 must be an integer containing
  29356.        the value of the font input record’s device field.
  29357.  
  29358. Figure 22 shows the structure of a font characterization table and, on the right, the
  29359. values it contains for the Macintosh screen.
  29360.  
  29361. •••Refer to Figure 22.•••
  29362.  
  29363. Figure 22–Font Characterization Table
  29364.  
  29365. The first two words of the font characterization table contain the approximate number
  29366. of dots per inch on the device. These values are only used for scaling between devices;
  29367. they don’t necessarily correspond to a device’s actual resolution.
  29368.  
  29369. The remainder of the table consists of three-byte triplets providing information
  29370. about the different stylistic variations. For all but the triplet defining the underline
  29371. characteristics:
  29372.  
  29373.   •  The first byte in the triplet indicates which byte beyond the bold
  29374.      field of the font output record (see below) is affected by the triplet.
  29375.   •  The second byte contains the amount to be stored in the affected field.
  29376.   •  The third byte indicates the amount by which the extra field of the
  29377.      font output record is to be incremented (starting from 0).
  29378.  
  29379. The triplet defining the underline characteristics indicates the amount by which the
  29380. font output record’s ulOffset, ulShadow, and ulThick fields
  29381. (respectively) should be incremented.
  29382.  
  29383. æKY FMOutput
  29384. FMOutPtr
  29385. æFc Fonts.h
  29386. æT struct
  29387. æD struct FMOutput {
  29388.     short errNum;
  29389.     Handle fontHandle;
  29390.     unsigned char boldPixels;
  29391.     unsigned char italicPixels;
  29392.     unsigned char ulOffset;
  29393.     unsigned char ulShadow;
  29394.     unsigned char ulThick;
  29395.     unsigned char shadowPixels;
  29396.     char extra;
  29397.     unsigned char ascent;
  29398.     unsigned char descent;
  29399.     unsigned char widMax;
  29400.     char leading;
  29401.     char unused;
  29402.     Point numer;
  29403.     Point denom;
  29404. };
  29405.  
  29406. typedef struct FMOutput FMOutput;
  29407. typedef FMOutput *FMOutPtr;
  29408.  
  29409. æC 
  29410.  
  29411. Based on the information in the font characterization table, the Font Manager determines
  29412. the optimum ascent, descent, and leading, so that the highest-quality printing or
  29413. drawing available will be produced. It then stores this information in a font output
  29414. record:
  29415.  
  29416. TYPE FMOutput = PACKED RECORD
  29417.                   errNum:      INTEGER;     {not used}
  29418.                   fontHandle:  Handle;      {handle to font record}
  29419.                   bold:        Byte;        {bold factor}
  29420.                   italic:      Byte;        {italic factor}
  29421.                   ulOffset:    Byte;        {underline offset}
  29422.                   ulShadow:    Byte;        {underline shadow}
  29423.                   ulThick:     Byte;        {underline thickness}
  29424.                   shadow:      Byte;        {shadow factor}
  29425.                   extra:       SignedByte;  {width of style}
  29426.                   ascent:      Byte;        {ascent}
  29427.                   descent:     Byte;        {descent}
  29428.                   widMax:      Byte;        {maximum character width}
  29429.                   leading:     SignedByte;  {leading}
  29430.                   unused:      Byte;        {not used}
  29431.                   numer:       Point;       {numerators of scaling factors}
  29432.                   denom:       Point        {denominators of scaling factors}
  29433.                 END;
  29434.  
  29435. ErrNum is reserved for future use, and is set to 0. FontHandle is a handle to the
  29436. font record of the font, as described in the next section. Bold, italic, ulOffset,
  29437. ulShadow, ulThick, and shadow are all fields that modify the way stylistic variations
  29438. are done; their values are taken from the font characterization table, and are used
  29439. by QuickDraw. (You’ll need to experiment with these values if you want to determine
  29440. exactly how they’re used.) Extra indicates the number of pixels that each character
  29441. has been widened by stylistic variation. For example, using the screen values shown
  29442. in Figure 22, the extra field for bold shadowed characters would be 3. Ascent, descent,
  29443. widMax, and leading are the same as the fields of the FontInfo record returned by the
  29444. QuickDraw procedure GetFontInfo. Numer and denom contain the scaling factors.
  29445.  
  29446. Just before returning this record to QuickDraw, the Font Manager calls the device
  29447. driver’s control routine to allow the driver to make any final modifications to the
  29448. record. Finally, the font information is returned to QuickDraw via a pointer to the
  29449. record, defined as follows:
  29450.  
  29451. TYPE FMOutPtr = ^FMOutput;
  29452.  
  29453. Note:  If you want to make your own calls to the device driver’s Control
  29454.        function, the reference number must be the driver reference number
  29455.        from the font input record’s device field, csCode must be 8, csParam
  29456.        must be a pointer to the font output record, and csParam+4 must be
  29457.        the value of the font input record’s device field.
  29458.  
  29459. æKY FontRec
  29460. æFc Fonts.h
  29461. æT struct
  29462. æD struct FontRec {
  29463.     short fontType; /*font type*/
  29464.     short firstChar; /*ASCII code of first character*/
  29465.     short lastChar; /*ASCII code of last character*/
  29466.     short widMax; /*maximum character width*/
  29467.     short kernMax; /*negative of maximum character kern*/
  29468.     short nDescent; /*negative of descent*/
  29469.     short fRectWidth; /*width of font rectangle*/
  29470.     short fRectHeight; /*height of font rectangle*/
  29471.     short owTLoc; /*offset to offset/width table*/
  29472.     short ascent; /*ascent*/
  29473.     short descent; /*descent*/
  29474.     short leading; /*leading*/
  29475.     short rowWords; /*row width of bit image / 2 */
  29476. };
  29477.  
  29478. typedef struct FontRec FontRec;
  29479. æC 
  29480.  
  29481. »Font Records
  29482.  
  29483. The information describing a font is contained in a data structure called a font
  29484. record, which contains the following:
  29485.  
  29486.   •  the font type (fixed-width or proportional)
  29487.   •  the ASCII code of the first character and the last character in the font
  29488.   •  the maximum character width and maximum amount any character kerns
  29489.   •  the font height, ascent, descent, and leading
  29490.   •  the bit image of the font
  29491.   •  a location table, which is an array of words specifying the location
  29492.      of each character image within the bit image
  29493.   •  an offset/width table, which is an array of words specifying the
  29494.      character offset and character width for each character in the font
  29495.  
  29496. For every character, the location table contains a word that specifies the bit offset
  29497. to the location of that character’s image in the bit image. The entry for a character
  29498. missing from the font contains the same value as the entry for the next character.
  29499. The last word of the table contains the offset to one bit beyond the end of the bit
  29500. image (that is, beyond the character image for the missing symbol). The image width
  29501. of each character is determined from the location table by subtracting the bit offset
  29502. to that character from the bit offset to the next character in the table.
  29503.  
  29504. There’s also one word in the offset/width table for every character:  The high-order
  29505. byte specifies the character offset and the low order byte specifies the character
  29506. width. Missing characters are flagged in this table by a word value of –1. The last
  29507. word is also –1, indicating the end of the table.
  29508.  
  29509. Note:  The 64K ROM version of the Resource Manager limits the total space
  29510.        occupied by the bit image, location table, offset/width table, and
  29511.        character-width and image-height tables to 32K bytes. For this reason,
  29512.        the practical limit on the font size of a full font is about 40 points.
  29513.  
  29514. Figure 9 illustrates a sample location table and offset/width table corresponding to
  29515. the bit image in Figure 8 above.
  29516.  
  29517. A font record is referred to by a handle that you can get by calling the FMSwapFont
  29518. function or the Resource Manager function GetResource. The data type for a font
  29519. record is as follows:
  29520.  
  29521. TYPE FontRec = RECORD
  29522.                  fontType:     INTEGER;    {font type}
  29523.                  firstChar:    INTEGER;    {ASCII code of first character}
  29524.                  lastChar:     INTEGER;    {ASCII code of last character}
  29525.                  widMax:       INTEGER;    {maximum character width}
  29526.                  kernMax:      INTEGER;    {negative of maximum character kern}
  29527.                  nDescent:     INTEGER;    {negative of descent}
  29528.                  fRectWidth:   INTEGER;    {width of font rectangle}
  29529.                  fRectHeight:  INTEGER;    {height of font rectangle}
  29530.                  owTLoc:       INTEGER;    {offset to offset/width table}
  29531.                  ascent:       INTEGER;    {ascent}
  29532.                  descent:      INTEGER;    {descent}
  29533.                  leading:      INTEGER;    {leading}
  29534.                  rowWords:     INTEGER;    {row width of bit image / 2}
  29535.                { bitImage:     ARRAY[1..rowWords,1..fRectHeight] OF INTEGER; }
  29536.                                            {bit image}
  29537.                { locTable:     ARRAY[firstChar..lastChar+2] OF INTEGER; }
  29538.                                            {location table}
  29539.                { owTable:      ARRAY[firstChar..lastChar+2] OF INTEGER; }
  29540.                                            {offset/width table}
  29541.                END;
  29542.  
  29543. Note:  The variable-length arrays appear as comments because they’re
  29544.        not valid Pascal syntax; they’re used only as conceptual aids.
  29545.  
  29546. •••Refer to Figure 9.•••
  29547.  
  29548. Figure 9–Sample Location Table and Offset/Width Table
  29549.  
  29550. The fontType field must contain one of the following predefined constants:
  29551.  
  29552. CONST  propFont   = $9000;    {proportional font}
  29553.        fixedFont  = $B000;    {fixed-width font}
  29554.  
  29555. The values in the widMax, kernMax, nDescent, fRectWidth, fRectHeight, ascent, descent,
  29556. and leading fields all specify a number of pixels.
  29557.  
  29558. KernMax indicates the largest number of pixels any character kerns, that is, the
  29559. distance from the character origin to the left edge of the font rectangle. It should
  29560. always be 0 or negative, since the kerned pixels are to the left of the character
  29561. origin. NDescent is the negative of the descent (the distance from the character
  29562. origin to the bottom of the font rectangle).
  29563.  
  29564. The owTLoc field contains a word offset from itself to the offset/width table; it’s
  29565. equivalent to
  29566.  
  29567.   4 + (rowWords * fRectHeight) + (lastChar–firstChar+3) + 1
  29568.  
  29569. Warning:  Remember, the offset and row width in a font record are
  29570.           given in words, not bytes.
  29571.  
  29572. Assembly-language note:  The global variable ROMFont0 contains a handle
  29573.                          to the font record for the system font.
  29574.  
  29575. Every size of a font is stored as a separate resource.  The resource type for a font
  29576. is 'FONT'.  The resource data for a font is simply a font record:
  29577.  
  29578.   Number of bytes    Contents
  29579.  
  29580.       2 bytes        FontType field of font record
  29581.       2 bytes        FirstChar field of font record
  29582.       2 bytes        LastChar field of font record
  29583.       2 bytes        WidMax field of font record
  29584.       2 bytes        KernMax field of font record
  29585.       2 bytes        NDescent field of font record
  29586.       2 bytes        FRectWidth field of font record
  29587.       2 bytes        FRectHeight field of font record
  29588.       2 bytes        OWTLoc field of font record
  29589.       2 bytes        Ascent field of font record
  29590.       2 bytes        Descent field of font record
  29591.       2 bytes        Leading field of font record
  29592.       2 bytes        RowWords field of font record
  29593.       n bytes        Bit image of font
  29594.                          n = 2 * rowWords * fRectHeight
  29595.       m bytes        Location table of font
  29596.                          m = 2 * (lastChar–firstChar+3)
  29597.       m bytes        Offset/width table of font
  29598.                          m = 2 * (lastChar–firstChar+3)
  29599.  
  29600. As shown in Figure 10, the resource ID of a font has the following format:  Bits 0-6
  29601. are the font size, bits 7-14 are the font number, and bit 15 is 0. Thus the resource
  29602. ID corresponding to a given font number and size is
  29603.  
  29604.   (128 * font number) + font size
  29605.  
  29606. •••Refer to Technical Note #245:•••
  29607.  
  29608. Since 0 is not a valid font size, the resource ID having 0 in the size field is used
  29609. to provide only the name of the font:  The name of the resource is the font name. For
  29610. example, for a font named Griffin and numbered 200, the resource naming the font
  29611. would have a resource ID of 25600 and the resource name
  29612. 'Griffin'. Size 10 of that font would be stored in a resource numbered 25610.
  29613.  
  29614. •••Refer to Figure 10.•••
  29615.  
  29616. Figure 10–Resource ID for a Font
  29617.  
  29618. The resource type 'FRSV' is reserved by the Font Manager; it identifies fonts used by
  29619. the system. Fonts whose resource IDs are contained in a 'FRSV' resource 1 will not be
  29620. removed from the system resource file by the Font/DA Mover. The format of a 'FRSV'
  29621. resource is as follows:
  29622.  
  29623.   Number of bytes    Contents
  29624.  
  29625.       2 bytes        Number of font resource IDs
  29626.       n * 2 bytes    n font resource IDs
  29627.  
  29628. æKY FMetricRec
  29629. æFc Fonts.h
  29630. æT struct
  29631. æD struct FMetricRec {
  29632.     Fixed ascent; /*base line to top*/
  29633.     Fixed descent; /*base line to bottom*/
  29634.     Fixed leading; /*leading between lines*/
  29635.     Fixed widMax; /*maximum character width*/
  29636.     Handle wTabHandle; /*handle to font width table*/
  29637. };
  29638.  
  29639. typedef struct FMetricRec FMetricRec;
  29640. æC 
  29641.  
  29642. æKY WidEntry
  29643. æFc Fonts.h
  29644. æT struct
  29645. æD struct WidEntry {
  29646.     short widStyle; /*style entry applies to*/
  29647. };
  29648.  
  29649. typedef struct WidEntry WidEntry;
  29650. æC 
  29651.  
  29652. æKY WidTable
  29653. æFc Fonts.h
  29654. æT struct
  29655. æD struct WidTable {
  29656.     short numWidths; /*number of entries - 1*/
  29657. };
  29658.  
  29659. typedef struct WidTable WidTable;
  29660. æC 
  29661.  
  29662. æKY AsscEntry
  29663. æFc Fonts.h
  29664. æT struct
  29665. æD struct AsscEntry {
  29666.     short fontSize;
  29667.     short fontStyle;
  29668.     short fontID; /*font resource ID*/
  29669. };
  29670.  
  29671. typedef struct AsscEntry AsscEntry;
  29672. æC 
  29673.  
  29674. æKY FontAssoc
  29675. æFc Fonts.h
  29676. æT struct
  29677. æD struct FontAssoc {
  29678.     short numAssoc; /*number of entries - 1*/
  29679. };
  29680.  
  29681. typedef struct FontAssoc FontAssoc;
  29682. æC 
  29683.  
  29684. æKY StyleTable
  29685. æFc Fonts.h
  29686. æT struct
  29687. æD struct StyleTable {
  29688.     short fontClass;
  29689.     long offset;
  29690.     long reserved;
  29691.     char indexes[48];
  29692. };
  29693.  
  29694. typedef struct StyleTable StyleTable;
  29695. æC 
  29696.  
  29697. æKY NameTable
  29698. æFc Fonts.h
  29699. æT struct
  29700. æD struct NameTable {
  29701.     short stringCount;
  29702.     Str255 baseFontName;
  29703. };
  29704.  
  29705. typedef struct NameTable NameTable;
  29706. æC 
  29707.  
  29708. æKY KernPair
  29709. æFc Fonts.h
  29710. æT struct
  29711. æD struct KernPair {
  29712.     char kernFirst; /*1st character of kerned pair*/
  29713.     char kernSecond; /*2nd character of kerned pair*/
  29714.     short kernWidth; /*kerning in 1pt fixed format*/
  29715. };
  29716.  
  29717. typedef struct KernPair KernPair;
  29718. æC 
  29719.  
  29720. æKY KernEntry
  29721. æFc Fonts.h
  29722. æT struct
  29723. æD struct KernEntry {
  29724.     short kernLength; /*length of this entry*/
  29725.     short kernStyle; /*style the entry applies to*/
  29726. };
  29727.  
  29728. typedef struct KernEntry KernEntry;
  29729. æC 
  29730.  
  29731. æKY KernTable
  29732. æFc Fonts.h
  29733. æT struct
  29734. æD struct KernTable {
  29735.     short numKerns; /*number of kerning entries*/
  29736. };
  29737.  
  29738. typedef struct KernTable KernTable;
  29739. æC 
  29740.  
  29741. æKY WidthTable
  29742. æFc Fonts.h
  29743. æT struct
  29744. æD struct WidthTable {
  29745.     Fixed tabData[256]; /*character widths*/
  29746.     Handle tabFont; /*font record used to build table*/
  29747.     long sExtra; /*space extra used for table*/
  29748.     long style; /*extra due to style*/
  29749.     short fID; /*font family ID*/
  29750.     short fSize; /*font size request*/
  29751.     short face; /*style (face) request*/
  29752.     short device; /*device requested*/
  29753.     Point inNumer; /*scale factors requested*/
  29754.     Point inDenom; /*scale factors requested*/
  29755.     short aFID; /*actual font family ID for table*/
  29756.     Handle fHand; /*family record used to build up table*/
  29757.     Boolean usedFam; /*used fixed point family widths*/
  29758.     unsigned char aFace; /*actual face produced*/
  29759.     short vOutput; /*vertical scale output value*/
  29760.     short hOutput; /*horizontal scale output value*/
  29761.     short vFactor; /*vertical scale output value*/
  29762.     short hFactor; /*horizontal scale output value*/
  29763.     short aSize; /*actual size of actual font used*/
  29764.     short tabSize; /*total size of table*/
  29765. };
  29766.  
  29767. typedef struct WidthTable WidthTable;
  29768. æC 
  29769. »Global Width Tables
  29770.  
  29771. Note:  The extensions to the Font Manager described in the following paragraphs
  29772.        were originally documented in Inside Macintosh, Volume IV.  As such,
  29773.        this information refers to the 128K ROMs and System file version 3.2
  29774.        and later.
  29775.  
  29776. The Font Manager communicates fractional character widths to QuickDraw via a global
  29777. width table, a data structure allocated in the system heap. A handle to the global
  29778. width table is returned by the FontMetrics procedure. The format of the global width
  29779. table is follows:
  29780.  
  29781. TYPE WidthTable = RECORD
  29782.                     tabData:  ARRAY[1..256] OF Fixed; { character widths}
  29783.                     tabFont:  Handle;   {font record used to build table}
  29784.                     sExtra:   LONGINT;  {space extra used for table}
  29785.                     style:    LONGINT;  {extra due to style}
  29786.                     fID:      INTEGER;  {font family ID}
  29787.                     fSize:    INTEGER;  {font size request}
  29788.                     face:     INTEGER;  {style (face) request}
  29789.                     device:   INTEGER;  {device requested}
  29790.                     inNumer:  Point;    {numerators of scaling factors}
  29791.                     inDenom:  Point;    {denominators of scaling factors}
  29792.                     aFID:     INTEGER;  {actual font family ID for table}
  29793.                     fHand:    handle;   {family record used to build table}
  29794.                     usedFam:  BOOLEAN;  {used fixed-point family widths}
  29795.                     aFace:    Byte;     {actual face produced}
  29796.                     vOutput:  INTEGER;  {vertical factor for expanding }
  29797.                                         { characters}
  29798.                     hOutput:  INTEGER;  {horizontal factor for expanding }
  29799.                                         { characters}
  29800.                     vFactor:  INTEGER;  {not used}
  29801.                     hFactor:  INTEGER;  {horizontal factor for increasing }
  29802.                                         { character widths}
  29803.                     aSize:    INTEGER;  {actual size of actual font used}
  29804.                     tabSize:  INTEGER   {total size of table}
  29805.                   END;
  29806.  
  29807. TabData is an array containing a character width for each of the 255 possible characters
  29808. in a font, plus one long word for the font’s missing symbol. The widths are stored in
  29809. the standard 32-bit fixed-point format. If a character is missing, its entry contains
  29810. the width of the missing symbol. (For efficiency, the Font Manager will store up to
  29811. 12 recently used global width tables.) InNumer and inDenom contain the vertical and
  29812. horizontal scaling factors copied from the font input record.
  29813.  
  29814. Scaling is effected in two ways:  by expanding characters of the chosen font and by
  29815. artificially increasing the widths of the chosen font in the width table. HOutput and
  29816. vOutput give the factors by which characters are to be expanded horizontally and
  29817. vertically. HFactor is the factor by which the widths of the chosen font, after
  29818. stylistic variations, have been increased. (VFactor is not used.) Thus, multiplying
  29819. hOutput and vOutput by hFactor and vFactor gives the true font scaling; the product
  29820. of hOutput and an entry in the width table is that character’s true scaled width.
  29821. HOutput,vOutput, hFactor, and vFactor are all 16-bit fixed-point numbers, with an
  29822. integer part in the high-order byte and a fractional part in the low-order byte.
  29823.  
  29824. If font scaling has been enabled, hFactor and vFactor both have a value of 1. In any
  29825. case, hOutput, vOutput, hFactor, and vFactor are adjusted so that the values of
  29826. hFactor and vFactor lie between 1 and 2, including 1.
  29827.  
  29828. Assembly-language note:  A handle to the global width table is contained
  29829.                          in the global variable WidthTabHandle. A pointer
  29830.                          to the table is contained in the global variable
  29831.                          WidthPtr; it’s reliable immediately after a call
  29832.                          to FMSwapFont but, like all pointers, may become
  29833.                          invalid after a call to the Memory Manager.
  29834.  
  29835.                          The global variable WidthListHand is a handle to a
  29836.                          list of handles to up to 12 recently-used width
  29837.                          tables. You can scan this list, looking for width
  29838.                          tables that match the family number, size, and style
  29839.                          of the font you wish to measure. If you reach a width
  29840.                          handle that’s equal to –1, that width table is
  29841.                          invalid, and you must make an FMSwapFont call to
  29842.                          get a valid one. When you reach a handle that’s zero,
  29843.                          you’ve reached the end of the list.
  29844.  
  29845.                          You should not use the global width table when
  29846.                          special international interface software is being
  29847.                          used to accommodate non-Roman alphabets. You can
  29848.                          recognize such software by looking at the global
  29849.                          variable IntlSpec; if it’s greater than 0, special
  29850.                          international software is installed. If your
  29851.                          application uses non-Roman alphabets, write to
  29852.  
  29853.                              Developer Technical Support
  29854.                              Apple Computer, Inc.
  29855.                              20525 Mariani Avenue, M/S 75-3T
  29856.                              Cupertino, CA 95014
  29857.  
  29858.                          for the latest version of the International Utilities
  29859.                          Package, which will be extended to handle non-Roman
  29860.                          alphabets.
  29861.  
  29862. æKY FamRec
  29863. æFc Fonts.h
  29864. æT struct
  29865. æD struct FamRec {
  29866.     short ffFlags; /*flags for family*/
  29867.     short ffFamID; /*family ID number*/
  29868.     short ffFirstChar; /*ASCII code of 1st character*/
  29869.     short ffLastChar; /*ASCII code of last character*/
  29870.     short ffAscent; /*maximum ascent for 1pt font*/
  29871.     short ffDescent; /*maximum descent for 1pt font*/
  29872.     short ffLeading; /*maximum leading for 1pt font*/
  29873.     short ffWidMax; /*maximum widMax for 1pt font*/
  29874.     long ffWTabOff; /*offset to width table*/
  29875.     long ffKernOff; /*offset to kerning table*/
  29876.     long ffStylOff; /*offset to style mapping table*/
  29877.     short ffProperty[9]; /*style property info*/
  29878.     short ffIntl[2]; /*for international use*/
  29879.     short ffVersion; /*version number*/
  29880. };
  29881.  
  29882. typedef struct FamRec FamRec;
  29883. æC 
  29884. »Family Records
  29885.  
  29886. Note:  The extensions to the Font Manager described in the following paragraphs
  29887.        were originally documented in Inside Macintosh, Volume IV.  As such,
  29888.        this information refers to the 128K ROMs and System file version 3.2
  29889.        and later.
  29890.  
  29891. Assembly-language note:  The global variable LastFOND is a handle to the last
  29892.                          family record used. You can read the contents of the
  29893.                          family record by using this handle. You should not
  29894.                          alter the contents of this record.
  29895.  
  29896. The data type for a family record is as follows:
  29897.  
  29898. TYPE FamRec = RECORD
  29899.                 ffFlags:      INTEGER;    {flags for family}
  29900.                 ffFamID:      INTEGER;    {family ID number}
  29901.                 ffFirstChar:  INTEGER;    {ASCII code of the first character}
  29902.                 ffLastChar:   INTEGER;    {ASCII code of the last character}
  29903.                 ffAscent:     INTEGER;    {maximum ascent for 1-pt.font}
  29904.                 ffDescent:    INTEGER;    {maximum descent for 1-pt.font}
  29905.                 ffLeading:    INTEGER;    {maximum leading for 1-pt.font}
  29906.                 ffWidMax:     INTEGER;    {maximum width for 1-pt.font}
  29907.                 ffWTabOff:    LONGINT;    {offset to width table}
  29908.                 ffKernOff:    LONGINT;    {offset to kerning table}
  29909.                 ffStylOff:    LONGINT;    {offset to style-mapping table}
  29910.                 ffProperty:   ARRAY[1..9] OF INTEGER; {style property info}
  29911.                 ffIntl:       ARRAY[1..2] OF INTEGER; {reserved}
  29912.                 ffVersion:    INTEGER;    {version number}
  29913.              {  ffAssoc:      FontAssoc;} {font association table}
  29914.              {  ffWidthTab:   WidTable;}  {width table}
  29915.              {  ffStyTab:     StyleTable;}{style-mapping table}
  29916.              {  ffKernTab:    KernTable;} {kerning table}
  29917.               END;
  29918.  
  29919. Note:  The variable-length arrays appear as comments because they’re not
  29920.        valid Pascal syntax; they’re used only as conceptual aids.  This
  29921.        version of the FamRec is accurate for Volume IV; the extensions to
  29922.        the FamRec made in Volume V are not included here.
  29923.  
  29924. The ffFlags field defines general characteristics of the font family, as follows:
  29925.  
  29926.   Bit    Meaning
  29927.   0      Set if there’s an image-height table
  29928.   1      Set if there’s a character-width table
  29929.   2–11   Reserved (should be zero)
  29930.   12     Set to ignore FractEnable when deciding whether to use
  29931.          fixed-point values for stylistic variations (see bit 13),
  29932.          clear to treat FractEnable as usual
  29933.   13     Set to use integer extra width for stylistic variations,
  29934.          clear to compute fixed-point extra width from the family
  29935.          style-mapping table when FractEnable is TRUE
  29936.   14     Set if family fractional-width table is not used, clear
  29937.          if table is used
  29938.   15     Set for fixed-width font, clear for proportional font
  29939.  
  29940. The values in the ffAscent, ffDescent, ffLeading, and ffWidMax describe the maximum
  29941. dimensions of the family as they would be for a hypothetical one-point font to be
  29942. scaled up. They use a special 16-bit fixed-point format with an integer part in the
  29943. high-order 4 bits and a fractional part in the low-order 12 bits. The FontMetrics
  29944. procedure calculates the true values by multiplying this number by the actual point
  29945. size.
  29946.  
  29947. The ffWTabOff, ffKernOff, and ffStylOff fields are offsets from the top of the record
  29948. to the start of the width table, kerning table, and style-mapping table, respectively;
  29949. if any of these fields is zero, the corresponding table does not exist.
  29950.  
  29951. The ffProperty field is the family style-property table, shown in Figure 11.
  29952.  
  29953. •••Refer to Figure 11.•••
  29954.  
  29955. Figure 11–Family Style-Property Table
  29956.  
  29957. Each entry is a 16-bit fixed-point number with a signed integer part in the high-order
  29958. 4 bits and a fractional part in the low-order 12 bits. These numbers are used to
  29959. calculate the amount of extra width for special stylistic variations; each of these
  29960. values is multiplied by the point size of the font actually being used. If the font
  29961. already exists for a given style, the value in its field is ignored.
  29962.  
  29963. The ffAssoc field contains the font association table. This table, shown in Figure
  29964. 12, is used to match a given font size and style combination with the resource ID of
  29965. an actual font.
  29966.  
  29967. •••Refer to Figure 12.•••
  29968.  
  29969. Figure 12–Font Association Table
  29970.  
  29971. Note:  In order to reduce search time, the Font Manager requires that
  29972.        the entries be sorted according to the fontSize field, with the
  29973.        smallest sizes first. If multiple fonts from the same family, the
  29974.        plain (roman) fonts come first. The Font Manager is optimized to
  29975.        look first for 'NFNT' resources, then 'FONT' resources.
  29976.  
  29977. Each entry in the font association table has the format shown in Figure 13.
  29978.  
  29979. •••Refer to Figure 13.•••
  29980.  
  29981. Figure 13–Font Association Table Entry
  29982.  
  29983. The font association table is followed by the family character-width table. As shown
  29984. in Figure 14, this table is actually a number of width tables (since a font family
  29985. may include numerous styles).
  29986.  
  29987. •••Refer to Figure 14.•••
  29988.  
  29989. Figure 14–Family Character-Width Table
  29990.  
  29991. Each character-width table is preceded by a style code; the low-order byte of this
  29992. word specifies stylistic variations (see Figure 15). The widths in each table are for
  29993. a hypothetical one-point font; the actual values for the characters are calculated by
  29994. multiplying these widths by the font size. The widths in this table are stored in a
  29995. 16-bit fixed-point format with an unsigned integer part in the high-order 4 bits and
  29996. a fractional part in the low-order 12 bits.
  29997.  
  29998. •••Refer to Figure 15.•••
  29999.  
  30000. Figure 15–Style Codes
  30001.  
  30002. The style-mapping table and its associated tables are used by the LaserWriter driver
  30003. and are described in the Apple LaserWriter Reference.
  30004.  
  30005. The kerning table, like the family character-width table, is actually a number of
  30006. kerning tables (see Figure 16).
  30007.  
  30008. •••Refer to Figure 16.•••
  30009.  
  30010. Figure 16–Kerning Table
  30011.  
  30012. Each kerning table is preceded by a style code; stored in the low-order byte of the
  30013. word, this style information has the same format shown in Figure 15 above. The number
  30014. of entries in the table follows the style word (see Figure 17).
  30015.  
  30016. •••Refer to Figure 17.•••
  30017.  
  30018. Figure 17–Structure of a Kerning Table
  30019.  
  30020. The entries in each kerning table (shown in Figure 18) consist of a pair of characters
  30021. followed by a kerning offset for a hypothetical one-point font. This value, represented
  30022. by an integer part in the high-order 4 bits and a fractional part in the low-order 12
  30023. bits, is multiplied by the size of the font to obtain the actual offset.
  30024.  
  30025. •••Refer to Figure 18.•••
  30026.  
  30027. Figure 18–Kerning Table Entry
  30028.  
  30029. Note:  The extensions to the Font Manager described in the following paragraphs
  30030.        were originally documented in Inside Macintosh, Volume V.  As such,
  30031.        this information refers to the Macintosh SE and Macintosh II ROMs and
  30032.        System file version 4.1 and later.
  30033.  
  30034. For Macintosh II only, bits 8 and 9 of the font style word within each font association
  30035. table specify the font depth; they must contain the same value as bits 2 and 3 of the
  30036. fontType field of the font record.  All other undefined bits remain 0.
  30037.  
  30038. A font family is stored as a resource of type 'FOND', and with the Macintosh II, it’s
  30039. format has been extended.  The new format is the following (with extension fields
  30040. indicated by asterisks):
  30041.  
  30042.   Number of bytes    Contents
  30043.  
  30044.       2 bytes        FONDFlags field of family record
  30045.       2 bytes        FONDFamID field of family record
  30046.       2 bytes        FONDFirst field of family record
  30047.       2 bytes        FONDLast field of family record
  30048.       2 bytes        FONDAscent field of family record
  30049.       2 bytes        FONDDescent field of family record
  30050.       2 bytes        FONDLeading field of family record
  30051.       2 bytes        FONDWidMax field of family record
  30052.       4 bytes        FONDWTabOff of family record
  30053.       4 bytes        FONDKernOff of family record
  30054.       4 bytes        FONDStylOff of family record
  30055.       24 bytes       FONDProperty field of family record
  30056.       4 bytes        FONDIntl field of family record
  30057.       2 bytes        *Version number ($02)
  30058.       m bytes        FONDAssoc field of family record (variable length)
  30059.       2 bytes        *Number of offsets minus 1
  30060.       4 bytes        *Offset to bounding box table
  30061.       n bytes        *Bounding box table
  30062.       p bytes        FONDWidTable field of family record (variable length)
  30063.       q bytes        FONDStylTab field of family record (variable length)
  30064.       r bytes        FONDKerntab field of family record (variable length)
  30065.  
  30066. The bounding box table has an entry for each style available in the family.  The
  30067. table as a whole has this form:
  30068.  
  30069.   Number of bytes    Contents
  30070.  
  30071.       2 bytes        Number of entries minus 1
  30072.       10 bytes       First entry
  30073.       10 bytes       Second entry . . .
  30074.  
  30075. Each bounding box entry has this form, giving the bounding box position with respect
  30076. to the origin of the characters:
  30077.  
  30078.   Number of bytes    Contents
  30079.  
  30080.       2 bytes        Style word
  30081.       2 bytes        Lower left x coordinate
  30082.       2 bytes        Lower left y coordinate
  30083.       2 bytes        Upper right x coordinate
  30084.       2 bytes        Upper right y coordinate
  30085.  
  30086. Note:  The extensions to the Font Manager described in the following paragraphs
  30087.        were originally documented in Inside Macintosh, Volume IV.  As such,
  30088.        this information refers to the 128K ROMs and System file version 3.2
  30089.        and later.
  30090.  
  30091. æKY InitFonts
  30092. æFc Fonts.h
  30093. æT Function
  30094. æTN A8FE
  30095. æD pascal void InitFonts(void)
  30096.     = 0xA8FE; 
  30097. æDT InitFonts()(void);
  30098. æMM
  30099. æRT 72
  30100. æRI I-222, P-31, 95, 101, 107, 112, 118, 174
  30101. æC  
  30102. InitFonts initializes the Font Manager. If the system font isn’t already in memory,
  30103. InitFonts reads it into memory. Call this procedure once before all other Font Manager
  30104. routines or any Toolbox routine that will call the Font Manager.
  30105.  
  30106. æKY GetFontName
  30107. æFc Fonts.h
  30108. æT Function
  30109. æTN A8FF
  30110. æD pascal void GetFontName(short familyID,Str255 theName)
  30111.     = 0xA8FF; 
  30112. æDT GetFontName((short) familyID,(Str255) theName);
  30113. æMM
  30114. æRT 191
  30115. æRI I-223
  30116. æC  
  30117. Warning:  Before returning, the routines in this section issue the Resource
  30118.           Manager call SetResLoad(TRUE). If your program previously called
  30119.           SetResLoad(FALSE) and you still want that to be in effect after
  30120.           calling one of these Font Manager routines, you’ll have to call
  30121.           SetResLoad(FALSE) again.
  30122.  
  30123. PROCEDURE GetFontName (fontNum:  INTEGER; VAR theName:  Str255);
  30124.  
  30125. Assembly-language note:  The macro you invoke to call GetFontName from
  30126.                          assembly language is named _GetFName.
  30127.  
  30128. GetFontName returns in theName the name of the font having the font number fontNum.
  30129. If there’s no such font, GetFontName returns the empty string.
  30130.  
  30131. æKY GetFNum
  30132. æFc Fonts.h
  30133. æT Function
  30134. æTN A900
  30135. æD pascal void GetFNum(const Str255 theName,short *familyID)
  30136.     = 0xA900; 
  30137. æDT GetFNum((const Str255) theName,(short *) familyID);
  30138. æMM
  30139. æRT 191
  30140. æRI I-223
  30141. æC  
  30142. Warning:  Before returning, the routines in this section issue the Resource
  30143.           Manager call SetResLoad(TRUE). If your program previously called
  30144.           SetResLoad(FALSE) and you still want that to be in effect after
  30145.           calling one of these Font Manager routines, you’ll have to call
  30146.           SetResLoad(FALSE) again.
  30147.  
  30148.  
  30149. GetFNum returns in theNum the font number for the font having the given fontName. If
  30150. there’s no such font, GetFNum returns 0.
  30151.  
  30152. æKY RealFont
  30153. æFc Fonts.h
  30154. æT Function
  30155. æTN A902
  30156. æD pascal Boolean RealFont(short fontNum,short size)
  30157.     = 0xA902; 
  30158. æDT Boolean myVariable = RealFont((short) fontNum,(short) size);
  30159. æMM
  30160. æRI I-223
  30161. æC  
  30162. Warning:  Before returning, the routines in this section issue the Resource
  30163.           Manager call SetResLoad(TRUE). If your program previously called
  30164.           SetResLoad(FALSE) and you still want that to be in effect after
  30165.           calling one of these Font Manager routines, you’ll have to call
  30166.           SetResLoad(FALSE) again.
  30167.  
  30168. RealFont returns TRUE if the font having the font number fontNum is available in the
  30169. given size in a resource file, or FALSE if the font has to be scaled to that size.
  30170.  
  30171. Note:  RealFont will always return FALSE if you pass applFont in fontNum.
  30172.        To find out if the application font is available in a particular
  30173.        size, call GetFontName and then GetFNum to get the actual font
  30174.        number for the application font, and then call RealFont with that number.
  30175.  
  30176. æKY SetFontLock
  30177. æFc Fonts.h
  30178. æT Function
  30179. æTN A903
  30180. æD pascal void SetFontLock(Boolean lockFlag)
  30181.     = 0xA903; 
  30182. æDT SetFontLock((Boolean) lockFlag);
  30183. æMM
  30184. æRI I-223
  30185. æC  
  30186. SetFontLock applies to the font in which text was most recently drawn. If lockFlag is
  30187. TRUE, SetFontLock makes the font unpurgeable (reading it into memory if it isn’t
  30188. already there). If lockFlag is FALSE, it releases the memory occupied by the font 
  30189. (by calling the Resource Manager procedure ReleaseResource).
  30190. Since fonts are normally purgeable, this procedure is useful for making a font temporarily
  30191. unpurgeable.
  30192.  
  30193. æKY FMSwapFont
  30194. æFc Fonts.h
  30195. æT Function
  30196. æTN A901
  30197. æD pascal FMOutPtr FMSwapFont(const FMInput *inRec)
  30198.     = 0xA901; 
  30199. æDT FMOutPtr myVariable = FMSwapFont((const FMInput *) inRec);
  30200. æMM
  30201. æRI I-223
  30202. æC 
  30203. The following low-level routine is called by QuickDraw and won’t normally be used by
  30204. an application directly, but it may be of interest to advanced programmers who want
  30205. to bypass the QuickDraw routines that deal with text.
  30206.  
  30207. FUNCTION FMSwapFont (inRec:  FMInput) :  FMOutPtr;
  30208.  
  30209. FMSwapFont returns a pointer to a font output record containing the size, style, and
  30210. other information about an adapted version of the font requested in the given font
  30211. input record. (Font input and output records are explained in the following section.)
  30212. FMSwapFont is called by QuickDraw every time a QuickDraw routine that does anything
  30213. with text is used. If you want to call FMSwapFont yourself, you must build a font
  30214. input record and then use the pointer returned by FMSwapFont to access the resulting
  30215. font output record.
  30216.  
  30217. æKY SetFScaleDisable
  30218. æFc Fonts.h
  30219. æT Function
  30220. æTN A834
  30221. æD pascal void SetFScaleDisable(Boolean fscaleDisable)
  30222.     = 0xA834; 
  30223. æDT SetFScaleDisable((Boolean) fscaleDisable);
  30224. æRI IV-32
  30225. æC  
  30226.  
  30227. Note:  The extensions to the Font Manager described in the following paragraphs
  30228.        were originally documented in Inside Macintosh, Volume IV.  As such,
  30229.        this information refers to the 128K ROMs and System file version 3.2
  30230.        and later.
  30231.  
  30232. SetFScaleDisable lets you disable or enable font scaling. If fScaleDisable is
  30233. TRUE, font scaling is disabled and the Font Manager returns an unscaled font with
  30234. more space around the characters; if it’s FALSE, the Font Manager scales fonts. To
  30235. ensure compatibility with existing applications, the Font Manager defaults to scaling
  30236. fonts.
  30237.  
  30238. Assembly-language note:  All programmers should use the SetFScaleDisable
  30239.                          procedure to disable and enable font scaling. In
  30240.                          particular, setting the global variable FScaleDisable
  30241.                          is insufficient.
  30242.  
  30243. æKY FontMetrics
  30244. æFc Fonts.h
  30245. æT Function
  30246. æTN A835
  30247. æD pascal void FontMetrics(const FMetricRec *theMetrics)
  30248.     = 0xA835; 
  30249. æDT FontMetrics((const FMetricRec *) theMetrics);
  30250. æMM
  30251. æRI IV-32
  30252. æC  
  30253. Note:  The extensions to the Font Manager described in the following paragraphs
  30254.        were originally documented in Inside Macintosh, Volume IV.  As such,
  30255.        this information refers to the 128K ROMs and System file version 3.2
  30256.        and later.
  30257.  
  30258. To improve the speed and readability of text display in your application, use the
  30259. SetFractEnable and SetFScaleDisable procedures to enable fractional character widths
  30260. and disable font scaling. Certain applications do not work properly when fractional
  30261. character widths are used and font scaling is disabled, so these features are turned
  30262. off by default.
  30263.  
  30264. The FontMetrics function is much like QuickDraw’s GetFontInfo function except that it
  30265. returns fixed-point values, letting you draw characters in more precise locations on
  30266. the screen.
  30267.  
  30268. If there’s a 'FOND' resource associated with the most recently drawn font, making the
  30269. font resource purgeable or unpurgeable with the SetFontLock procedure will make the
  30270. 'FOND' resource resource purgeable or unpurgeable as well.
  30271.  
  30272. PROCEDURE FontMetrics (VAR theMetrics:  FMetricRec);
  30273.  
  30274. FontMetrics is similar to the QuickDraw procedure GetFontInfo except that it returns
  30275. fixed-point values for greater accuracy in high-resolution printing.
  30276.  
  30277. The FMetricRec data structure is defined as follows:
  30278.  
  30279. TYPE FMetricRec = RECORD
  30280.                     ascent:      Fixed;    {ascent}
  30281.                     descent:     Fixed;    {descent}
  30282.                     leading:     Fixed;    {leading}
  30283.                     widMax:      Fixed;    {maximum character width}
  30284.                     wTabHandle:  Handle;   {handle to global width table}
  30285.                   END;
  30286.  
  30287. Ascent, descent, leading, and widMax are identical in function to their counterparts
  30288. in GetFontInfo. WTabHandle is a handle to the global width table
  30289. (described below).
  30290.  
  30291. æKY SetFractEnable
  30292. æFc Fonts.h
  30293. æT Function
  30294. æD pascal void SetFractEnable(Boolean fractEnable); 
  30295. æDT SetFractEnable((Boolean) fractEnable);
  30296. æRT 72
  30297. æRI V-180
  30298. æC  
  30299. Note:  The extensions to the Font Manager described in the following paragraphs
  30300.        were originally documented in Inside Macintosh, Volume IV.  As such,
  30301.        this information refers to the 128K ROMs and System file version 3.2
  30302.        and later.
  30303.  
  30304. SetFractEnable lets you enable or disable fractional character widths. If fractEnable
  30305. is TRUE, fractional character widths are enabled; if it’s FALSE, the Font Manager
  30306. uses integer widths. To ensure compatibility with existing applications, fractional
  30307. character widths are disabled by default.
  30308.  
  30309. SetFractEnable, which was not in the 128K ROM (but was available in the Pascal interfaces)
  30310. has been added to both the Macintosh SE and Macintosh II ROMs.
  30311.  
  30312. Assembly-language note:   Assembly-language programmers should call
  30313.                           SetFractEnable rather than change the value
  30314.                           of the global variable FractEnable.
  30315.  
  30316. æKY getfnum
  30317. æFc Fonts.h
  30318. æT Function
  30319. æD void getfnum(char *theName,short *familyID); 
  30320. æDT getfnum((char *) theName,(short *) familyID);
  30321. æMM
  30322. æRT 191
  30323. æRI I-223
  30324. æC  
  30325. Warning:  Before returning, the routines in this section issue the Resource
  30326.           Manager call SetResLoad(TRUE). If your program previously called
  30327.           SetResLoad(FALSE) and you still want that to be in effect after
  30328.           calling one of these Font Manager routines, you’ll have to call
  30329.           SetResLoad(FALSE) again.
  30330.  
  30331.  
  30332. GetFNum returns in theNum the font number for the font having the given fontName. If
  30333. there’s no such font, GetFNum returns 0.
  30334.  
  30335. æKY getfontname
  30336. æFc Fonts.h
  30337. æT Function
  30338. æD void getfontname(short familyID,char *theName); 
  30339. æDT getfontname((short) familyID,(char *) theName);
  30340. æMM
  30341. æRT 191
  30342. æRI I-223
  30343. æC  
  30344. Warning:  Before returning, the routines in this section issue the Resource
  30345.           Manager call SetResLoad(TRUE). If your program previously called
  30346.           SetResLoad(FALSE) and you still want that to be in effect after
  30347.           calling one of these Font Manager routines, you’ll have to call
  30348.           SetResLoad(FALSE) again.
  30349.  
  30350. PROCEDURE GetFontName (fontNum:  INTEGER; VAR theName:  Str255);
  30351.  
  30352. Assembly-language note:  The macro you invoke to call GetFontName from
  30353.                          assembly language is named _GetFName.
  30354.  
  30355. GetFontName returns in theName the name of the font having the font number fontNum.
  30356. If there’s no such font, GetFontName returns the empty string.
  30357.  
  30358.  
  30359. æKY GestaltEqu.h
  30360. æKL Gestalt
  30361. NewGestalt
  30362. ReplaceGestalt
  30363.  
  30364. gestalt32BitAddressing
  30365. gestalt32BitCapable
  30366. gestalt32BitQD
  30367. gestalt32BitSysZone
  30368. gestalt68000
  30369. gestalt68010
  30370. gestalt68020
  30371. gestalt68030
  30372. gestalt68030MMU
  30373. gestalt68040
  30374. gestalt68040FPU
  30375. gestalt68040MMU
  30376. gestalt68851
  30377. gestalt68881
  30378. gestalt68882
  30379. gestalt8BitQD
  30380. gestaltAddressingModeAttr
  30381. gestaltAliasMgrAttr
  30382. gestaltAliasMgrPresent
  30383. gestaltAMU
  30384. gestaltAppleEventsAttr
  30385. gestaltAppleEventsPresent
  30386. gestaltAppleTalkVersion
  30387. gestaltAUXVersion
  30388. gestaltClassic
  30389. gestaltCTBVersion
  30390. gestaltDBAccessMgrAttr
  30391. gestaltDBAccessMgrPresent
  30392. gestaltDupSelectorErr
  30393. gestaltEditionMgrAttr
  30394. gestaltEditionMgrPresent
  30395. gestaltElmerISOKbd
  30396. gestaltElmerKbd
  30397. gestaltExtADBKbd
  30398. gestaltExtendedTimeMgr
  30399. gestaltExtISOADBKbd
  30400. gestaltFolderMgrAttr
  30401. gestaltFolderMgrPresent
  30402. gestaltFontMgrAttr
  30403. gestaltFPUType
  30404. gestaltHardwareAttr
  30405. gestaltHasASC
  30406. gestaltHasParityCapability
  30407. gestaltHasSCC
  30408. gestaltHasSCSI
  30409. gestaltHasVIA1
  30410. gestaltHasVIA2
  30411. gestaltHelpMgrAttr
  30412. gestaltHelpMgrPresent
  30413. gestaltIPCSupport
  30414. gestaltKeyboardType
  30415. gestaltLaunchCanReturn
  30416. gestaltLaunchControl
  30417. gestaltLaunchFullFileSpec
  30418. gestaltLocationErr
  30419. gestaltLogicalPageSize
  30420. gestaltLogicalRAMSize
  30421. gestaltLowMemorySize
  30422. gestaltMac512KE
  30423. gestaltMacAndPad
  30424. gestaltMachineType
  30425. gestaltMacII
  30426. gestaltMacIIci
  30427. gestaltMacIIcx
  30428. gestaltMacIIfx
  30429. gestaltMacIIx
  30430. gestaltMacKbd
  30431. gestaltMacPlus
  30432. gestaltMacPlusKbd
  30433. gestaltMacSE
  30434. gestaltMacSE030
  30435. gestaltMacXL
  30436. gestaltMiscAttr
  30437. gestaltMMUType
  30438. gestaltNoFPU
  30439. gestaltNoMMU
  30440. gestaltNotificationMgrAttr
  30441. gestaltNotificationPresent
  30442. gestaltOriginalQD
  30443. gestaltOSAttr
  30444. gestaltOutlineFonts
  30445. gestaltParityAttr
  30446. gestaltParityEnabled
  30447. gestaltPartialRsrcs
  30448. gestaltPhysicalRAMSize
  30449. gestaltPMgrCPUIdle
  30450. gestaltPMgrExists
  30451. gestaltPMgrSCC
  30452. gestaltPMgrSound
  30453. gestaltPortable
  30454. gestaltPowerMgrAttr
  30455. gestaltPPCSupportsDontCare
  30456. gestaltPPCSupportsIncomming
  30457. gestaltPPCSupportsOutGoing
  30458. gestaltPPCSupportsRealTime
  30459. gestaltPPCSupportsStoreAndForward
  30460. gestaltPPCToolboxAttr
  30461. gestaltPPCToolboxPresent
  30462. gestaltProcessorType
  30463. gestaltPrtblADBKbd
  30464. gestaltPrtblISOKbd
  30465. gestaltQuickdrawVersion
  30466. gestaltRealTempMemory
  30467. gestaltResourceMgrAttr
  30468. gestaltRevisedTimeMgr
  30469. gestaltROMSize
  30470. gestaltROMVersion
  30471. gestaltScriptCount
  30472. gestaltScriptMgrVersion
  30473. gestaltScrollingThrottle
  30474. gestaltSoundAttr
  30475. gestaltStandardTimeMgr
  30476. gestaltStdADBKbd
  30477. gestaltStdISOADBKbd
  30478. gestaltStereoCapability
  30479. gestaltStereoMixing
  30480. gestaltSysDebuggerSupport
  30481. gestaltSystemVersion
  30482. gestaltSysZoneGrowable
  30483. gestaltTE1
  30484. gestaltTE2
  30485. gestaltTE3
  30486. gestaltTE4
  30487. gestaltTempMemSupport
  30488. gestaltTempMemTracked
  30489. gestaltTextEditVersion
  30490. gestaltTimeMgrVersion
  30491. gestaltUndefSelectorErr
  30492. gestaltUnknownErr
  30493. gestaltVersion
  30494. gestaltVMAttr
  30495. gestaltVMPresent
  30496.  
  30497. æKY gestaltUnknownErr
  30498. æFc GestaltEqu.h
  30499. æT #define
  30500. æD 
  30501. /* ***********************
  30502.  *    Gestalt error codes
  30503.  *********************** */
  30504.  
  30505. #define gestaltUnknownErr -5550 /* value returned if Gestalt doesn't know the answer */
  30506. æC 
  30507.  
  30508. æKY gestaltUndefSelectorErr
  30509. æFc GestaltEqu.h
  30510. æT #define
  30511. æD #define gestaltUndefSelectorErr -5551 /* undefined selector was passed to Gestalt */
  30512. æC 
  30513.  
  30514. æKY gestaltDupSelectorErr
  30515. æFc GestaltEqu.h
  30516. æT #define
  30517. æD #define gestaltDupSelectorErr -5552 /* tried to add an entry that already existed */
  30518. æC 
  30519.  
  30520. æKY gestaltLocationErr
  30521. æFc GestaltEqu.h
  30522. æT #define
  30523. æD #define gestaltLocationErr -5553 /* gestalt function ptr wasn't in sysheap */
  30524. æC 
  30525.  
  30526. æKY gestaltVersion
  30527. æFc GestaltEqu.h
  30528. æT #define
  30529. æD 
  30530. /* *************************
  30531.  *    Environment Selectors
  30532.  ************************* */
  30533.  
  30534. #define gestaltVersion 'vers' /* gestalt version */
  30535. æC 
  30536.  
  30537. æKY gestaltAddressingModeAttr
  30538. æFc GestaltEqu.h
  30539. æT #define
  30540. æD #define gestaltAddressingModeAttr 'addr' /* addressing mode attributes */
  30541. æC 
  30542.  
  30543. æKY gestalt32BitAddressing
  30544. æFc GestaltEqu.h
  30545. æT #define
  30546. æD #define gestalt32BitAddressing 0 /* using 32-bit addressing mode */
  30547. æC 
  30548.  
  30549. æKY gestalt32BitSysZone
  30550. æFc GestaltEqu.h
  30551. æT #define
  30552. æD #define gestalt32BitSysZone 1 /* 32-bit compatible system zone */
  30553. æC 
  30554.  
  30555. æKY gestalt32BitCapable
  30556. æFc GestaltEqu.h
  30557. æT #define
  30558. æD #define gestalt32BitCapable 2 /* Machine is 32-bit capable */
  30559. æC 
  30560.  
  30561. æKY gestaltAliasMgrAttr
  30562. æFc GestaltEqu.h
  30563. æT #define
  30564. æD #define gestaltAliasMgrAttr 'alis' /* Alias Mgr Attributes */
  30565. æC 
  30566.  
  30567. æKY gestaltAliasMgrPresent
  30568. æFc GestaltEqu.h
  30569. æT #define
  30570. æD #define gestaltAliasMgrPresent 0 /* True if the Alias Mgr is present */
  30571. æC 
  30572.  
  30573. æKY gestaltAppleTalkVersion
  30574. æFc GestaltEqu.h
  30575. æT #define
  30576. æD #define gestaltAppleTalkVersion 'atlk' /* appletalk version */
  30577. æC 
  30578.  
  30579. æKY gestaltAUXVersion
  30580. æFc GestaltEqu.h
  30581. æT #define
  30582. æD #define gestaltAUXVersion 'a/ux' /*a/ux version, if present */
  30583. æC 
  30584.  
  30585. æKY gestaltCTBVersion
  30586. æFc GestaltEqu.h
  30587. æT #define
  30588. æD #define gestaltCTBVersion 'ctbv' /* CommToolbox version */
  30589. æC 
  30590.  
  30591. æKY gestaltDBAccessMgrAttr
  30592. æFc GestaltEqu.h
  30593. æT #define
  30594. æD #define gestaltDBAccessMgrAttr 'dbac' /* Database Access Mgr attributes */
  30595. æC 
  30596.  
  30597. æKY gestaltDBAccessMgrPresent
  30598. æFc GestaltEqu.h
  30599. æT #define
  30600. æD #define gestaltDBAccessMgrPresent 0 /* True if Database Access Mgr present */
  30601. æC 
  30602.  
  30603. æKY gestaltEditionMgrAttr
  30604. æFc GestaltEqu.h
  30605. æT #define
  30606. æD #define gestaltEditionMgrAttr 'edtn' /* Edition Mgr attributes */
  30607. æC 
  30608.  
  30609. æKY gestaltEditionMgrPresent
  30610. æFc GestaltEqu.h
  30611. æT #define
  30612. æD #define gestaltEditionMgrPresent 0 /* True if Edition Mgr present */
  30613. æC 
  30614.  
  30615. æKY gestaltAppleEventsAttr
  30616. æFc GestaltEqu.h
  30617. æT #define
  30618. æD #define gestaltAppleEventsAttr 'evnt' /* Apple Events attributes */
  30619. æC 
  30620.  
  30621. æKY gestaltAppleEventsPresent
  30622. æFc GestaltEqu.h
  30623. æT #define
  30624. æD #define gestaltAppleEventsPresent 0 /* True if Apple Events present */
  30625. æC 
  30626.  
  30627. æKY gestaltFolderMgrAttr
  30628. æFc GestaltEqu.h
  30629. æT #define
  30630. æD #define gestaltFolderMgrAttr 'fold' /* Folder Mgr attributes */
  30631. æC 
  30632.  
  30633. æKY gestaltFolderMgrPresent
  30634. æFc GestaltEqu.h
  30635. æT #define
  30636. æD #define gestaltFolderMgrPresent 0 /* True if Folder Mgr present */
  30637. æC 
  30638.  
  30639. æKY gestaltFontMgrAttr
  30640. æFc GestaltEqu.h
  30641. æT #define
  30642. æD #define gestaltFontMgrAttr 'font' /* Font Mgr attributes */
  30643. æC 
  30644.  
  30645. æKY gestaltOutlineFonts
  30646. æFc GestaltEqu.h
  30647. æT #define
  30648. æD #define gestaltOutlineFonts 0 /* True if Outline Fonts supported */
  30649. æC 
  30650.  
  30651. æKY gestaltFPUType
  30652. æFc GestaltEqu.h
  30653. æT #define
  30654. æD #define gestaltFPUType 'fpu ' /* fpu type */
  30655. æC 
  30656.  
  30657. æKY gestaltNoFPU
  30658. æFc GestaltEqu.h
  30659. æT #define
  30660. æD #define gestaltNoFPU 0 /* no FPU */
  30661. æC 
  30662.  
  30663. æKY gestalt68881
  30664. æFc GestaltEqu.h
  30665. æT #define
  30666. æD #define gestalt68881 1 /* 68881 FPU */
  30667. æC 
  30668.  
  30669. æKY gestalt68882
  30670. æFc GestaltEqu.h
  30671. æT #define
  30672. æD #define gestalt68882 2 /* 68882 FPU */
  30673. æC 
  30674.  
  30675. æKY gestalt68040FPU
  30676. æFc GestaltEqu.h
  30677. æT #define
  30678. æD #define gestalt68040FPU 3 /* 68040 built-in FPU */
  30679. æC 
  30680.  
  30681. æKY gestaltHardwareAttr
  30682. æFc GestaltEqu.h
  30683. æT #define
  30684. æD #define gestaltHardwareAttr 'hdwr' /* hardware attributes */
  30685. æC 
  30686.  
  30687. æKY gestaltHasVIA1
  30688. æFc GestaltEqu.h
  30689. æT #define
  30690. æD #define gestaltHasVIA1 0 /* VIA1 exists */
  30691. æC 
  30692.  
  30693. æKY gestaltHasVIA2
  30694. æFc GestaltEqu.h
  30695. æT #define
  30696. æD #define gestaltHasVIA2 1 /* VIA2 exists */
  30697. æC 
  30698.  
  30699. æKY gestaltHasASC
  30700. æFc GestaltEqu.h
  30701. æT #define
  30702. æD #define gestaltHasASC 3 /* Apple Sound Chip exists */
  30703. æC 
  30704.  
  30705. æKY gestaltHasSCC
  30706. æFc GestaltEqu.h
  30707. æT #define
  30708. æD #define gestaltHasSCC 4 /* SCC exists */
  30709. æC 
  30710.  
  30711. æKY gestaltHasSCSI
  30712. æFc GestaltEqu.h
  30713. æT #define
  30714. æD #define gestaltHasSCSI 7 /* SCSI exists */
  30715. æC 
  30716.  
  30717. æKY gestaltHelpMgrAttr
  30718. æFc GestaltEqu.h
  30719. æT #define
  30720. æD #define gestaltHelpMgrAttr 'help' /* Help Mgr Attributes */
  30721. æC 
  30722.  
  30723. æKY gestaltHelpMgrPresent
  30724. æFc GestaltEqu.h
  30725. æT #define
  30726. æD #define gestaltHelpMgrPresent 0 /* true if help mgr is present */
  30727. æC 
  30728.  
  30729. æKY gestaltKeyboardType
  30730. æFc GestaltEqu.h
  30731. æT #define
  30732. æD #define gestaltKeyboardType 'kbd ' /* keyboard type */
  30733. æC 
  30734.  
  30735. æKY gestaltMacKbd
  30736. æFc GestaltEqu.h
  30737. æT #define
  30738. æD #define gestaltMacKbd 1
  30739. æC 
  30740.  
  30741. æKY gestaltMacAndPad
  30742. æFc GestaltEqu.h
  30743. æT #define
  30744. æD #define gestaltMacAndPad 2
  30745. æC 
  30746.  
  30747. æKY gestaltMacPlusKbd
  30748. æFc GestaltEqu.h
  30749. æT #define
  30750. æD #define gestaltMacPlusKbd 3
  30751. æC 
  30752.  
  30753. æKY gestaltExtADBKbd
  30754. æFc GestaltEqu.h
  30755. æT #define
  30756. æD #define gestaltExtADBKbd 4
  30757. æC 
  30758.  
  30759. æKY gestaltStdADBKbd
  30760. æFc GestaltEqu.h
  30761. æT #define
  30762. æD #define gestaltStdADBKbd 5
  30763. æC 
  30764.  
  30765. æKY gestaltPrtblADBKbd
  30766. æFc GestaltEqu.h
  30767. æT #define
  30768. æD #define gestaltPrtblADBKbd 6
  30769. æC 
  30770.  
  30771. æKY gestaltPrtblISOKbd
  30772. æFc GestaltEqu.h
  30773. æT #define
  30774. æD #define gestaltPrtblISOKbd 7
  30775. æC 
  30776.  
  30777. æKY gestaltStdISOADBKbd
  30778. æFc GestaltEqu.h
  30779. æT #define
  30780. æD #define gestaltStdISOADBKbd 8
  30781. æC 
  30782.  
  30783. æKY gestaltExtISOADBKbd
  30784. æFc GestaltEqu.h
  30785. æT #define
  30786. æD #define gestaltExtISOADBKbd 9
  30787. æC 
  30788.  
  30789. æKY gestaltElmerKbd
  30790. æFc GestaltEqu.h
  30791. æT #define
  30792. æD #define gestaltElmerKbd 10
  30793. æC 
  30794.  
  30795. æKY gestaltElmerISOKbd
  30796. æFc GestaltEqu.h
  30797. æT #define
  30798. æD #define gestaltElmerISOKbd 11
  30799. æC 
  30800.  
  30801. æKY gestaltLowMemorySize
  30802. æFc GestaltEqu.h
  30803. æT #define
  30804. æD #define gestaltLowMemorySize 'lmem' /* size of low memory area */
  30805. æC 
  30806.  
  30807. æKY gestaltLogicalRAMSize
  30808. æFc GestaltEqu.h
  30809. æT #define
  30810. æD #define gestaltLogicalRAMSize 'lram' /* logical ram size */
  30811. æC 
  30812.  
  30813. æKY gestaltMiscAttr
  30814. æFc GestaltEqu.h
  30815. æT #define
  30816. æD #define gestaltMiscAttr 'misc' /* miscellaneous attributes */
  30817. æC 
  30818.  
  30819. æKY gestaltScrollingThrottle
  30820. æFc GestaltEqu.h
  30821. æT #define
  30822. æD #define gestaltScrollingThrottle 0 /* true if scrolling throttle on */
  30823. æC 
  30824.  
  30825. æKY gestaltMMUType
  30826. æFc GestaltEqu.h
  30827. æT #define
  30828. æD #define gestaltMMUType 'mmu ' /* mmu type */
  30829. æC 
  30830.  
  30831. æKY gestaltNoMMU
  30832. æFc GestaltEqu.h
  30833. æT #define
  30834. æD #define gestaltNoMMU 0 /* no MMU */
  30835. æC 
  30836.  
  30837. æKY gestaltAMU
  30838. æFc GestaltEqu.h
  30839. æT #define
  30840. æD #define gestaltAMU 1 /* address management unit */
  30841. æC 
  30842.  
  30843. æKY gestalt68851
  30844. æFc GestaltEqu.h
  30845. æT #define
  30846. æD #define gestalt68851 2 /* 68851 PMMU */
  30847. æC 
  30848.  
  30849. æKY gestalt68030MMU
  30850. æFc GestaltEqu.h
  30851. æT #define
  30852. æD #define gestalt68030MMU 3 /* 68030 built-in MMU */
  30853. æC 
  30854.  
  30855. æKY gestalt68040MMU
  30856. æFc GestaltEqu.h
  30857. æT #define
  30858. æD #define gestalt68040MMU 4 /* 68040 built-in MMU */
  30859. æC 
  30860.  
  30861. æKY gestaltNotificationMgrAttr
  30862. æFc GestaltEqu.h
  30863. æT #define
  30864. æD #define gestaltNotificationMgrAttr 'nmgr' /* notification manager attributes */
  30865. æC 
  30866.  
  30867. æKY gestaltNotificationPresent
  30868. æFc GestaltEqu.h
  30869. æT #define
  30870. æD #define gestaltNotificationPresent 0 /* notification manager exists */
  30871. æC 
  30872.  
  30873. æKY gestaltOSAttr
  30874. æFc GestaltEqu.h
  30875. æT #define
  30876. æD #define gestaltOSAttr 'os  ' /* o/s attributes */
  30877. æC 
  30878.  
  30879. æKY gestaltSysZoneGrowable
  30880. æFc GestaltEqu.h
  30881. æT #define
  30882. æD #define gestaltSysZoneGrowable 0 /* system heap is growable */
  30883. æC 
  30884.  
  30885. æKY gestaltLaunchCanReturn
  30886. æFc GestaltEqu.h
  30887. æT #define
  30888. æD #define gestaltLaunchCanReturn 1 /* can return from launch */
  30889. æC 
  30890.  
  30891. æKY gestaltLaunchFullFileSpec
  30892. æFc GestaltEqu.h
  30893. æT #define
  30894. æD #define gestaltLaunchFullFileSpec 2 /* can launch from full file spec */
  30895. æC 
  30896.  
  30897. æKY gestaltLaunchControl
  30898. æFc GestaltEqu.h
  30899. æT #define
  30900. æD #define gestaltLaunchControl 3 /* launch control support available */
  30901. æC 
  30902.  
  30903. æKY gestaltTempMemSupport
  30904. æFc GestaltEqu.h
  30905. æT #define
  30906. æD #define gestaltTempMemSupport 4 /* temp memory support */
  30907. æC 
  30908.  
  30909. æKY gestaltRealTempMemory
  30910. æFc GestaltEqu.h
  30911. æT #define
  30912. æD #define gestaltRealTempMemory 5 /* temp memory handles are real */
  30913. æC 
  30914.  
  30915. æKY gestaltTempMemTracked
  30916. æFc GestaltEqu.h
  30917. æT #define
  30918. æD #define gestaltTempMemTracked 6 /* temporary memory handles are tracked */
  30919. æC 
  30920.  
  30921. æKY gestaltIPCSupport
  30922. æFc GestaltEqu.h
  30923. æT #define
  30924. æD #define gestaltIPCSupport 7 /* IPC support is present */
  30925. æC 
  30926.  
  30927. æKY gestaltSysDebuggerSupport
  30928. æFc GestaltEqu.h
  30929. æT #define
  30930. æD #define gestaltSysDebuggerSupport 8 /* system debugger support is present */
  30931. æC 
  30932.  
  30933. æKY gestaltLogicalPageSize
  30934. æFc GestaltEqu.h
  30935. æT #define
  30936. æD #define gestaltLogicalPageSize 'pgsz' /* logical page size */
  30937. æC 
  30938.  
  30939. æKY gestaltPowerMgrAttr
  30940. æFc GestaltEqu.h
  30941. æT #define
  30942. æD #define gestaltPowerMgrAttr 'powr' /* power manager attributes */
  30943. æC 
  30944.  
  30945. æKY gestaltPMgrExists
  30946. æFc GestaltEqu.h
  30947. æT #define
  30948. æD #define gestaltPMgrExists 0
  30949. æC 
  30950.  
  30951. æKY gestaltPMgrCPUIdle
  30952. æFc GestaltEqu.h
  30953. æT #define
  30954. æD #define gestaltPMgrCPUIdle 1
  30955. æC 
  30956.  
  30957. æKY gestaltPMgrSCC
  30958. æFc GestaltEqu.h
  30959. æT #define
  30960. æD #define gestaltPMgrSCC 2
  30961. æC 
  30962.  
  30963. æKY gestaltPMgrSound
  30964. æFc GestaltEqu.h
  30965. æT #define
  30966. æD #define gestaltPMgrSound 3
  30967. æC 
  30968.  
  30969. æKY gestaltPPCToolboxAttr
  30970. æFc GestaltEqu.h
  30971. æT #define
  30972. æD #define gestaltPPCToolboxAttr 'ppc ' /* PPC toolbox attributes */
  30973. æC 
  30974.  
  30975. æKY gestaltPPCToolboxPresent
  30976. æFc GestaltEqu.h
  30977. æT #define
  30978. æD 
  30979. /* 
  30980.  * PPC will return the combination of following bit fields.
  30981.  * e.g. gestaltPPCSupportsRealTime +gestaltPPCSupportsIncomming + gestaltPPCSupportsOutGoing
  30982.  * indicates PPC is cuurently is only supports real time delivery
  30983.  * and both icoming and outgoing network sessions are allowed.
  30984.  * By default local real time delivery is supported as long as PPCInit has been called.
  30985.  */
  30986.  
  30987. #define gestaltPPCToolboxPresent 0x0000 /* PPC Toolbox is present  Requires PPCInit to be called */
  30988. æC 
  30989.  
  30990. æKY gestaltPPCSupportsRealTime
  30991. æFc GestaltEqu.h
  30992. æT #define
  30993. æD #define gestaltPPCSupportsRealTime 0x1000 /* PPC Supports real-time delivery */
  30994. æC 
  30995.  
  30996. æKY gestaltPPCSupportsStoreAndForward
  30997. æFc GestaltEqu.h
  30998. æT #define
  30999. æD #define gestaltPPCSupportsStoreAndForward 0x2000 /* PPC Store and Forward  delivery */
  31000. æC 
  31001.  
  31002. æKY gestaltPPCSupportsDontCare
  31003. æFc GestaltEqu.h
  31004. æT #define
  31005. æD #define gestaltPPCSupportsDontCare 0x4000 /* PPC Supports  Specification of Don't care */
  31006. æC 
  31007.  
  31008. æKY gestaltPPCSupportsIncomming
  31009. æFc GestaltEqu.h
  31010. æT #define
  31011. æD #define gestaltPPCSupportsIncomming 0x0001 /* PPC will deny incomming network requests */
  31012. æC 
  31013.  
  31014. æKY gestaltPPCSupportsOutGoing
  31015. æFc GestaltEqu.h
  31016. æT #define
  31017. æD #define gestaltPPCSupportsOutGoing 0x0002 /* PPC will deny outgoing network requests */
  31018. æC 
  31019.  
  31020. æKY gestaltProcessorType
  31021. æFc GestaltEqu.h
  31022. æT #define
  31023. æD #define gestaltProcessorType 'proc' /* processor type */
  31024. æC 
  31025.  
  31026. æKY gestalt68000
  31027. æFc GestaltEqu.h
  31028. æT #define
  31029. æD #define gestalt68000 1
  31030. æC 
  31031.  
  31032. æKY gestalt68010
  31033. æFc GestaltEqu.h
  31034. æT #define
  31035. æD #define gestalt68010 2
  31036. æC 
  31037.  
  31038. æKY gestalt68020
  31039. æFc GestaltEqu.h
  31040. æT #define
  31041. æD #define gestalt68020 3
  31042. æC 
  31043.  
  31044. æKY gestalt68030
  31045. æFc GestaltEqu.h
  31046. æT #define
  31047. æD #define gestalt68030 4
  31048. æC 
  31049.  
  31050. æKY gestalt68040
  31051. æFc GestaltEqu.h
  31052. æT #define
  31053. æD #define gestalt68040 5
  31054. æC 
  31055.  
  31056. æKY gestaltParityAttr
  31057. æFc GestaltEqu.h
  31058. æT #define
  31059. æD #define gestaltParityAttr 'prty' /* parity attributes */
  31060. æC 
  31061.  
  31062. æKY gestaltHasParityCapability
  31063. æFc GestaltEqu.h
  31064. æT #define
  31065. æD #define gestaltHasParityCapability 0 /* has ability to check parity */
  31066. æC 
  31067.  
  31068. æKY gestaltParityEnabled
  31069. æFc GestaltEqu.h
  31070. æT #define
  31071. æD #define gestaltParityEnabled 1 /* parity checking enabled */
  31072. æC 
  31073.  
  31074. æKY gestaltQuickdrawVersion
  31075. æFc GestaltEqu.h
  31076. æT #define
  31077. æD #define gestaltQuickdrawVersion 'qd  ' /* quickdraw version */
  31078. æC 
  31079.  
  31080. æKY gestaltOriginalQD
  31081. æFc GestaltEqu.h
  31082. æT #define
  31083. æD #define gestaltOriginalQD 0x000 /* original 1-bit QD            <3.2> */
  31084. æC 
  31085.  
  31086. æKY gestalt8BitQD
  31087. æFc GestaltEqu.h
  31088. æT #define
  31089. æD #define gestalt8BitQD 0x100 /* 8-bit color QD                <3.2> */
  31090. æC 
  31091.  
  31092. æKY gestalt32BitQD
  31093. æFc GestaltEqu.h
  31094. æT #define
  31095. æD #define gestalt32BitQD 0x200 /* 32-bit color QD                <3.2> */
  31096. æC 
  31097.  
  31098. æKY gestaltPhysicalRAMSize
  31099. æFc GestaltEqu.h
  31100. æT #define
  31101. æD #define gestaltPhysicalRAMSize 'ram ' /* physical RAM size */
  31102. æC 
  31103.  
  31104. æKY gestaltResourceMgrAttr
  31105. æFc GestaltEqu.h
  31106. æT #define
  31107. æD #define gestaltResourceMgrAttr 'rsrc' /* Resource Mgr attributes */
  31108. æC 
  31109.  
  31110. æKY gestaltPartialRsrcs
  31111. æFc GestaltEqu.h
  31112. æT #define
  31113. æD #define gestaltPartialRsrcs 0 /* True if partial resources exist */
  31114. æC 
  31115.  
  31116. æKY gestaltScriptMgrVersion
  31117. æFc GestaltEqu.h
  31118. æT #define
  31119. æD #define gestaltScriptMgrVersion 'scri' /* Script Manager version number    <08/05/89 pke> */
  31120. æC 
  31121.  
  31122. æKY gestaltScriptCount
  31123. æFc GestaltEqu.h
  31124. æT #define
  31125. æD #define gestaltScriptCount 'scr#' /* number of active script systems    <08/05/89 pke> */
  31126. æC 
  31127.  
  31128. æKY gestaltSoundAttr
  31129. æFc GestaltEqu.h
  31130. æT #define
  31131. æD #define gestaltSoundAttr 'snd ' /* sound attributes */
  31132. æC 
  31133.  
  31134. æKY gestaltStereoCapability
  31135. æFc GestaltEqu.h
  31136. æT #define
  31137. æD #define gestaltStereoCapability 0 /* sound hardware has stereo capability */
  31138. æC 
  31139.  
  31140. æKY gestaltStereoMixing
  31141. æFc GestaltEqu.h
  31142. æT #define
  31143. æD #define gestaltStereoMixing 1 /* stereo mixing on external speaker */
  31144. æC 
  31145.  
  31146. æKY gestaltTextEditVersion
  31147. æFc GestaltEqu.h
  31148. æT #define
  31149. æD #define gestaltTextEditVersion 'te  ' /* TextEdit version number            <08/05/89 pke> */
  31150. æC 
  31151.  
  31152. æKY gestaltTE1
  31153. æFc GestaltEqu.h
  31154. æT #define
  31155. æD #define gestaltTE1 1 /* TextEdit in MacIIci ROM <8Aug89smb> */
  31156. æC 
  31157.  
  31158. æKY gestaltTE2
  31159. æFc GestaltEqu.h
  31160. æT #define
  31161. æD #define gestaltTE2 2 /* TextEdit with 6.0.4 Script Systems on MacIIci (Script bug fixes for MacIIci) <8Aug89smb> */
  31162. æC 
  31163.  
  31164. æKY gestaltTE3
  31165. æFc GestaltEqu.h
  31166. æT #define
  31167. æD #define gestaltTE3 3 /* TextEdit with 6.0.4 Script Systems all but MacIIci <8Aug89smb> */
  31168. æC 
  31169.  
  31170. æKY gestaltTE4
  31171. æFc GestaltEqu.h
  31172. æT #define
  31173. æD 
  31174. /*  **** Following is for System 7.0 Only **** */
  31175.  
  31176. #define gestaltTE4 4 /* TextEdit in System 7.0*/
  31177. æC 
  31178.  
  31179. æKY gestaltTimeMgrVersion
  31180. æFc GestaltEqu.h
  31181. æT #define
  31182. æD #define gestaltTimeMgrVersion 'tmgr' /* time mgr version */
  31183. æC 
  31184.  
  31185. æKY gestaltStandardTimeMgr
  31186. æFc GestaltEqu.h
  31187. æT #define
  31188. æD #define gestaltStandardTimeMgr 1 /* standard time mgr is present */
  31189. æC 
  31190.  
  31191. æKY gestaltRevisedTimeMgr
  31192. æFc GestaltEqu.h
  31193. æT #define
  31194. æD #define gestaltRevisedTimeMgr 2 /* revised time mgr is present */
  31195. æC 
  31196.  
  31197. æKY gestaltExtendedTimeMgr
  31198. æFc GestaltEqu.h
  31199. æT #define
  31200. æD #define gestaltExtendedTimeMgr 3 /* extended time mgr is present */
  31201. æC 
  31202.  
  31203. æKY gestaltVMAttr
  31204. æFc GestaltEqu.h
  31205. æT #define
  31206. æD #define gestaltVMAttr 'vm  ' /* virtual memory attributes */
  31207. æC 
  31208.  
  31209. æKY gestaltVMPresent
  31210. æFc GestaltEqu.h
  31211. æT #define
  31212. æD #define gestaltVMPresent 0 /* true if virtual memory is present */
  31213. æC 
  31214.  
  31215. æKY gestaltMachineType
  31216. æFc GestaltEqu.h
  31217. æT #define
  31218. æD 
  31219. /* ************************
  31220.  *    Info-only selectors
  31221.  *********************** */
  31222.  
  31223. #define gestaltMachineType 'mach' /* machine type */
  31224. æC 
  31225.  
  31226. æKY gestaltClassic
  31227. æFc GestaltEqu.h
  31228. æT #define
  31229. æD #define gestaltClassic 1
  31230. æC 
  31231.  
  31232. æKY gestaltMacXL
  31233. æFc GestaltEqu.h
  31234. æT #define
  31235. æD #define gestaltMacXL 2
  31236. æC 
  31237.  
  31238. æKY gestaltMac512KE
  31239. æFc GestaltEqu.h
  31240. æT #define
  31241. æD #define gestaltMac512KE 3
  31242. æC 
  31243.  
  31244. æKY gestaltMacPlus
  31245. æFc GestaltEqu.h
  31246. æT #define
  31247. æD #define gestaltMacPlus 4
  31248. æC 
  31249.  
  31250. æKY gestaltMacSE
  31251. æFc GestaltEqu.h
  31252. æT #define
  31253. æD #define gestaltMacSE 5
  31254. æC 
  31255.  
  31256. æKY gestaltMacII
  31257. æFc GestaltEqu.h
  31258. æT #define
  31259. æD #define gestaltMacII 6
  31260. æC 
  31261.  
  31262. æKY gestaltMacIIx
  31263. æFc GestaltEqu.h
  31264. æT #define
  31265. æD #define gestaltMacIIx 7
  31266. æC 
  31267.  
  31268. æKY gestaltMacIIcx
  31269. æFc GestaltEqu.h
  31270. æT #define
  31271. æD #define gestaltMacIIcx 8
  31272. æC 
  31273.  
  31274. æKY gestaltMacSE030
  31275. æFc GestaltEqu.h
  31276. æT #define
  31277. æD #define gestaltMacSE030 9
  31278. æC 
  31279.  
  31280. æKY gestaltPortable
  31281. æFc GestaltEqu.h
  31282. æT #define
  31283. æD #define gestaltPortable 10
  31284. æC 
  31285.  
  31286. æKY gestaltMacIIci
  31287. æFc GestaltEqu.h
  31288. æT #define
  31289. æD #define gestaltMacIIci 11
  31290. æC 
  31291.  
  31292. æKY gestaltMacIIfx
  31293. æFc GestaltEqu.h
  31294. æT #define
  31295. æD #define gestaltMacIIfx 13
  31296. æC 
  31297.  
  31298. æKY gestaltROMSize
  31299. æFc GestaltEqu.h
  31300. æT #define
  31301. æD #define gestaltROMSize 'rom ' /* rom size */
  31302. æC 
  31303.  
  31304. æKY gestaltROMVersion
  31305. æFc GestaltEqu.h
  31306. æT #define
  31307. æD #define gestaltROMVersion 'romv' /* rom version */
  31308. æC 
  31309.  
  31310. æKY gestaltSystemVersion
  31311. æFc GestaltEqu.h
  31312. æT #define
  31313. æD #define gestaltSystemVersion 'sysv' /* system version*/
  31314. æC 
  31315.  
  31316. æKY Gestalt
  31317. æFc GestaltEqu.h
  31318. æT Function
  31319. æD pascal OSErr Gestalt(OSType selector,long *response); 
  31320. æDT OSErr myVariable = Gestalt((OSType) selector,(long *) response);
  31321. æC 
  31322. Use the Gestalt function to obtain information about the operating environment.
  31323. The information you need is indicated by the selector parameter, which Gestalt
  31324. must already recognize.
  31325.  
  31326. Trap macro  _Gestalt
  31327. On entry    D0: selector code
  31328. On exit     A0: response
  31329.             D0: result code
  31330.  
  31331. Upon successful completion of the function, the response parameter contains the
  31332. information requested. Note that Gestalt returns the results from all function
  31333. selectors in a long integer, occupying 4 bytes. In some cases, not all 4 bytes
  31334. are needed to hold the returned information, in which case Gestalt places the
  31335. information in the low-order bytes of the response parameter.
  31336.  
  31337. Result codes
  31338. noErr                        0  No error
  31339. gestaltUnknownErr        –5550  Could not obtain the response
  31340. gestaltUndefSelectorErr  –5551  Undefined selector
  31341.  
  31342. æKY NewGestalt
  31343. æFc GestaltEqu.h
  31344. æT Function
  31345. æD pascal OSErr NewGestalt(OSType selector,ProcPtr gestaltFunction); 
  31346. æDT OSErr myVariable = NewGestalt((OSType) selector,(ProcPtr) gestaltFunction);
  31347. æC 
  31348. Use the NewGestalt function to add selector codes to those already recognized by
  31349. Gestalt.
  31350.  
  31351. Trap macro  _NewGestalt
  31352. On entry    A0: address of new selector function
  31353.             D0: selector code
  31354. On exit     D0: result code
  31355.  
  31356. NewGestalt takes as parameters the selector to be registered and the function
  31357. that Gestalt calls when it receives this selector. The interface for the
  31358. selectorFunction function is defined in “Specifying Gestalt Selector Functions”
  31359. earlier in this chapter.
  31360.  
  31361. Result codes
  31362. noErr                      0  No error
  31363. memFullErr              –108  Ran out of memory
  31364. gestaltDupSelectorErr  –5552  Selector already exists
  31365. gestaltLocationErr     –5553  Function not in system heap
  31366.  
  31367. æKY ReplaceGestalt
  31368. æFc GestaltEqu.h
  31369. æT Function
  31370. æD pascal OSErr ReplaceGestalt(OSType selector,ProcPtr gestaltFunction,ProcPtr *oldGestaltFunction); 
  31371. æDT OSErr myVariable = ReplaceGestalt((OSType) selector,(ProcPtr) gestaltFunction,(ProcPtr *) oldGestaltFunction);
  31372. æC 
  31373. The ReplaceGestalt function allows an application to replace the function that
  31374. is currently associated with a selector.
  31375.  
  31376. Trap macro  _ReplaceGestalt
  31377. On entry    A0: address of new selector function
  31378.             D0: selector code
  31379. On exit     A0: address of old selector function
  31380.             D0: result code
  31381.  
  31382. The interface for the selectorFunction function is defined in “Specifying
  31383. Gestalt Selector Functions” earlier in this chapter. The new function must
  31384. reside in the system heap and may want to call the function previously
  31385. associated with the named selector. It may do so by using the address returned
  31386. in the parameter oldGestaltFunction. If ReplaceGestalt returns an error of any
  31387. type, then the value of oldGestaltFunction is undefined.
  31388.  
  31389. Result codes
  31390. noErr                        0  No error
  31391. gestaltUndefSelectorErr  –5551  Undefined selector
  31392. gestaltLocationErr       –5553  Function not in system heap
  31393.  
  31394.  
  31395. æKY Globals
  31396. æKL ABusDCE
  31397. ABusVars
  31398. ACount
  31399. ADBBase
  31400. ANumber
  31401. ASCBase
  31402. AlarmState
  31403. ApFontID
  31404. AppParmHandle
  31405. ApplLimit
  31406. ApplScratch
  31407. ApplZone
  31408. BootDrive
  31409. BufPtr
  31410. BufTgDate
  31411. BufTgFBkNum
  31412. BufTgFFlg
  31413. BufTgFNum
  31414. BusErrVct
  31415. CPUFlag
  31416. CQDGlobals
  31417. CaretTime
  31418. ChunkyDepth
  31419. ColLines
  31420. CrsrAddr
  31421. CrsrBase
  31422. CrsrBusy
  31423. CrsrCouple
  31424. CrsrDevice
  31425. CrsrNew
  31426. CrsrObscure
  31427. CrsrPin
  31428. CrsrPtr
  31429. CrsrRect
  31430. CrsrRow
  31431. CrsrSave
  31432. CrsrScale
  31433. CrsrState
  31434. CrsrThresh
  31435. CrsrVis
  31436. CurActivate
  31437. CurApName
  31438. CurApRefNum
  31439. CurDeactive
  31440. CurDirStore
  31441. CurJTOffset
  31442. CurMap
  31443. CurPageOption
  31444. CurPitch
  31445. CurStackBase
  31446. CurrentA5
  31447. DABeeper
  31448. DAStrings
  31449. DSAlertRect
  31450. DSAlertTab
  31451. DSCtrAdj
  31452. DSDrawProc
  31453. DSErrCode
  31454. DSWndUpdate
  31455. DTQFlags
  31456. DTQueue
  31457. DTskQHdr
  31458. DTskQTail
  31459. DefVCBPtr
  31460. DefltStack
  31461. DeskHook
  31462. DeskPattern
  31463. DeviceList
  31464. DlgFont
  31465. DoubleTime
  31466. DragHook
  31467. DragPattern
  31468. DrvQHdr
  31469. DskErr
  31470. DskVerify
  31471. EjectNotify
  31472. EndSRTPtr
  31473. EventQueue
  31474. EvtBufCnt
  31475. ExpandMem
  31476. ExtStsDT
  31477. FCBSPtr
  31478. FSQHdr
  31479. FScaleDisable
  31480. FinderName
  31481. GZMoveHnd
  31482. GZRootHnd
  31483. GZRootPtr
  31484. GetParam
  31485. GhostWindow
  31486. GrayRgn
  31487. HeapEnd
  31488. HiHeapMark
  31489. HiKeyLast
  31490. HiliteMode
  31491. HiliteRGB
  31492. HpChk
  31493. IAZNotify
  31494. IWM
  31495. IconTLAddr
  31496. IntFlag
  31497. IntlSpec
  31498. JAllocCrsr
  31499. JCrsrTask
  31500. JDTInstall
  31501. JFetch
  31502. JGNEFilter
  31503. JIODone
  31504. JKybdTask
  31505. JOpcodeProc
  31506. JSetCCrsr
  31507. JStash
  31508. JSwapMMU
  31509. JVBLTask
  31510. JournalFlag
  31511. JournalRef
  31512. KbdLast
  31513. KbdType
  31514. KbdVars
  31515. Key1Trans
  31516. Key2Trans
  31517. KeyLast
  31518. KeyMVars
  31519. KeyMapLM
  31520. KeyRepThresh
  31521. KeyRepTime
  31522. KeyThresh
  31523. KeyTime
  31524. KeypadMap
  31525. LastTxGDevice
  31526. LaunchFlag
  31527. Lo3Bytes
  31528. LoadTrap
  31529. LoaderPBlock
  31530. Lvl1DT
  31531. Lvl2DT
  31532. MBState
  31533. MBTicks
  31534. MBarEnable
  31535. MBarHeight
  31536. MBarHook
  31537. MMDefFlags
  31538. MMU32bit
  31539. MMUFlags
  31540. MMUFluff
  31541. MMUTbl
  31542. MMUTblSize
  31543. MMUType
  31544. MTemp
  31545. MainDevice
  31546. MaskBC
  31547. MaskHandle
  31548. MaskPtr
  31549. MemErr
  31550. MemTop
  31551. MenuFlash
  31552. MenuHook
  31553. MenuList
  31554. MickeyBytes
  31555. MinStack
  31556. MinusOne
  31557. MmInOK
  31558. MonkeyLives
  31559. Mouse
  31560. MouseMask
  31561. MouseOffset
  31562. NMIFlag
  31563. NewCrsrJTbl
  31564. OldContent
  31565. OldStructure
  31566. OneOne
  31567. PCDeskPat
  31568. PWMBuf2
  31569. PaintWhite
  31570. PortAUse
  31571. PortBUse
  31572. PortList
  31573. PrintErr
  31574. QDColors
  31575. QDErrLM
  31576. QDExist
  31577. RAMBase
  31578. RGBBlack
  31579. RGBWhite
  31580. ROM85
  31581. ROMBase
  31582. ROMFont0
  31583. ROMMapHndl
  31584. RawMouse
  31585. ResErr
  31586. ResErrProc
  31587. ResLoad
  31588. ResReadOnly
  31589. RestProc
  31590. ResumeProc
  31591. RndSeed
  31592. RomMapInsert
  31593. RowBits
  31594. SCCASts
  31595. SCCBSts
  31596. SCCRd
  31597. SCCWr
  31598. SCSIBase
  31599. SCSIDMA
  31600. SCSIGlobals
  31601. SCSIHsk
  31602. SCSIPoll
  31603. SDMJmpTblPtr
  31604. SEVarBase
  31605. SEvtEnb
  31606. SFSaveDisk
  31607. SInfoPtr
  31608. SInitFlags
  31609. SMGlobals
  31610. SPATalkA
  31611. SPATalkB
  31612. SPAlarm
  31613. SPClikCaret
  31614. SPConfig
  31615. SPFont
  31616. SPKbd
  31617. SPMisc1
  31618. SPMisc2
  31619. SPPortA
  31620. SPPortB
  31621. SPPrint
  31622. SPValid
  31623. SPVolCtl
  31624. SRsrcTblPtr
  31625. SaveSegHandle
  31626. SaveUpdate
  31627. SaveVisRgn
  31628. ScrDmpEnb
  31629. ScrDmpType
  31630. ScrHRes
  31631. ScrVRes
  31632. ScrapCount
  31633. ScrapEnd
  31634. ScrapHandle
  31635. ScrapInfo
  31636. ScrapName
  31637. ScrapSize
  31638. ScrapState
  31639. ScrapTag
  31640. ScrapVars
  31641. Scratch20
  31642. Scratch8
  31643. ScreenBytes
  31644. ScreenRow
  31645. ScrnBase
  31646. ScrnVBLPtr
  31647. SdVolume
  31648. SdmBusErr
  31649. SegHiEnable
  31650. SerialVars
  31651. SlotPrTbl
  31652. SlotQDT
  31653. SlotTICKS
  31654. SlotVBLQ
  31655. SoundActive
  31656. SoundBase
  31657. SoundDCE
  31658. SoundLevel
  31659. SoundPtr
  31660. SoundVBL
  31661. SrcDevice
  31662. StkLowPt
  31663. SwitcherTPtr
  31664. SysEvtBuf
  31665. SysEvtMask
  31666. SysMap
  31667. SysMapHndl
  31668. SysParam
  31669. SysResName
  31670. SysVersion
  31671. SysZone
  31672. TEDoText
  31673. TERecal
  31674. TEScrpHandle
  31675. TEScrpLength
  31676. TESysJust
  31677. TEWdBreak
  31678. TableSeed
  31679. TagData
  31680. TheCrsr
  31681. TheGDevice
  31682. TheMenu
  31683. TheZone
  31684. Ticks
  31685. Time
  31686. TimeDBRA
  31687. TimeLM
  31688. TimeSCCDB
  31689. TimeSCSIDB
  31690. TmpResLoad
  31691. ToExtFS
  31692. ToolScratch
  31693. TopMapHndl
  31694. UTableBase
  31695. UnitNtryCnt
  31696. VBLQueue
  31697. VCBQHdr
  31698. VIA
  31699. VIA2DT
  31700. VertRRate
  31701. VidMode
  31702. VidType
  31703. VideoInfoOK
  31704. WMgrCPort
  31705. WMgrPort
  31706. WWExist
  31707. WarmStart
  31708. WindowList
  31709. WordRedraw
  31710.  
  31711. æKY ACount
  31712. æFc Globals
  31713. æD ACount  0xA9A [GLOBAL VAR] Stage number (0 through 3) of last alert (word)
  31714.  
  31715.  
  31716. æKY ANumber
  31717. æFc Globals
  31718. æD ANumber  0xA98 [GLOBAL VAR] Resource ID of last alert (word)
  31719.  
  31720.  
  31721. æKY ApFontID
  31722. æFc Globals
  31723. æD ApFontID 0x984 [GLOBAL VAR] Font number of application font (word)
  31724.  
  31725.  
  31726. æKY ApplScratch
  31727. æFc Globals
  31728. æD ApplScratch 0xA78 [GLOBAL VAR] 12-byte scratch area reserved for use by applications
  31729.  
  31730.  
  31731. æKY AppParmHandle
  31732. æFc Globals
  31733. æD AppParmHandle 0xAEC [GLOBAL VAR] Handle to Finder information
  31734.  
  31735.  
  31736. æKY DABeeper
  31737. æFc Globals
  31738. æD DABeeper 0xA9C [GLOBAL VAR] Address of current sound procedure
  31739.  
  31740.  
  31741. æKY DAStrings
  31742. æFc Globals
  31743. æD DAStrings 0xAA0 [GLOBAL VAR] Handles to ParamText strings (16 bytes) 
  31744.  
  31745.  
  31746. æKY DefVCBPtr
  31747. æFc Globals
  31748. æD DefVCBPtr 0x352 [GLOBAL VAR] Pointer to default volume control block 
  31749.  
  31750.  
  31751. æKY DlgFont
  31752. æFc Globals
  31753. æD DlgFont  0xAFA [GLOBAL VAR] Font number for dialogs and alerts (word)
  31754.  
  31755.  
  31756. æKY DragPattern
  31757. æFc Globals
  31758. æD DragPattern 0xA34 [GLOBAL VAR] Pattern of dragged region's outline (8 bytes)
  31759.  
  31760.  
  31761. æKY FCBSPtr
  31762. æFc Globals
  31763. æD FCBSPtr  0x34E [GLOBAL VAR] Pointer to file-control-block buffer
  31764.  
  31765.  
  31766. æKY FinderName
  31767. æFc Globals
  31768. æD FinderName 0x2E0 [GLOBAL VAR] Name of the Finder (length byte followed by up to 15 
  31769. characters)
  31770.  
  31771. æKY FScaleDisable
  31772. æFc Globals
  31773. æC FScaleDisable 0xA63 [GLOBAL VAR] Nonzero to disable font scaling (byte)
  31774.  
  31775.  
  31776. æKY FSQHdr
  31777. æFc Globals
  31778. æD FSQHdr  0x360 [GLOBAL VAR] File I/O queue header (10 bytes)
  31779.  
  31780.  
  31781. æKY MBarEnable
  31782. æFc Globals
  31783. æD MBarEnable 0xA20 [GLOBAL VAR] Unique menu ID for active desk accessory, when menu bar 
  31784.                  belongs to the accessory (word) 
  31785.  
  31786. æKY MBarHook
  31787. æFc Globals
  31788. æD MBarHook 0xA2C [GLOBAL VAR] Address of routine called by MenuSelect before menu is 
  31789.                drawn
  31790.  
  31791. æKY MenuFlash
  31792. æFc Globals
  31793. æD MenuFlash 0xA24 [GLOBAL VAR] Count for duration of menu item blinking (word)
  31794.  
  31795.  
  31796. æKY MenuHook
  31797. æFc Globals
  31798. æD MenuHook 0xA30 [GLOBAL VAR] Address of routine called during MenuSelect
  31799.  
  31800.  
  31801. æKY MenuList
  31802. æFc Globals
  31803. æD MenuList 0xA1C [GLOBAL VAR] Handle to current menu list
  31804.  
  31805.  
  31806. æKY OldContent
  31807. æFc Globals
  31808. æD OldContent 0x9EA [GLOBAL VAR] Handle to saved content region
  31809.  
  31810.  
  31811. æKY OldStructure
  31812. æFc Globals
  31813. æD OldStructure 0x9E6 [GLOBAL VAR] Handle to saved structure region
  31814.  
  31815.  
  31816. æKY PrintErr
  31817. æFc Globals
  31818. æD PrintErr 0x944 [GLOBAL VAR] Result code from last Printing Manager routine (word)
  31819.  
  31820.  
  31821. æKY ROMFont0
  31822. æFc Globals
  31823. æD ROMFont0 0x980 [GLOBAL VAR] Handle to font record for system font
  31824.  
  31825.  
  31826. æKY SaveUpdate
  31827. æFc Globals
  31828. æD SaveUpdate 0x9DA [GLOBAL VAR] Flag for whether to generate update events (word)
  31829.  
  31830.  
  31831. æKY SaveVisRgn
  31832. æFc Globals
  31833. æD SaveVisRgn 0x9F2 [GLOBAL VAR] Handle to saved visRgn
  31834.  
  31835.  
  31836. æKY TheMenu
  31837. æFc Globals
  31838. æD TheMenu  0xA26 [GLOBAL VAR] Menu ID of currently highlighted menu (word)
  31839.  
  31840.  
  31841. æKY ToExtFS
  31842. æFc Globals
  31843. æD ToExtFS  0x3F2 [GLOBAL VAR] Pointer to external file system
  31844.  
  31845.  
  31846. æKY ToolScratch
  31847. æFc Globals
  31848. æD ToolScratch 0x9CE [GLOBAL VAR] 8-byte scratch area
  31849.  
  31850.  
  31851. æKY VCBQHdr
  31852. æFc Globals
  31853. æD VCBQHdr  0x356 [GLOBAL VAR] Volume-control-block queue header (10 bytes)
  31854.  
  31855.  
  31856.  
  31857. æKY Graf3D.h
  31858. æKL Clip3D
  31859. GetPort3D
  31860. Identity
  31861. InitGrf3d
  31862. Line2D
  31863. Line3D
  31864. LineTo2D
  31865. LineTo3D
  31866. LookAt
  31867. Move2D
  31868. Move3D
  31869. MoveTo2D
  31870. MoveTo3D
  31871. Open3DPort
  31872. Pitch
  31873. Roll
  31874. Scale
  31875. SetPort3D
  31876. SetPt2D
  31877. SetPt3D
  31878. Skew
  31879. Transform
  31880. Translate
  31881. ViewAngle
  31882. ViewPort
  31883. Yaw
  31884.  
  31885. Point2D
  31886. Point3D
  31887. Port3D
  31888. Port3DHandle
  31889. Port3DPtr
  31890. radConst
  31891. XfMatrix
  31892.  
  31893. æKY radConst
  31894. æFc Graf3D.h
  31895. æT #define
  31896. æD #define radConst 3754936
  31897. æC 
  31898.  
  31899. æKY XfMatrix
  31900. æFc Graf3D.h
  31901. æT typedef
  31902. æD typedef Fixed XfMatrix[4][4];
  31903. æC 
  31904.  
  31905. æKY Point3D
  31906. æFc Graf3D.h
  31907. æT struct
  31908. æD struct Point3D {
  31909.     Fixed x;
  31910.     Fixed y;
  31911.     Fixed z;
  31912. };
  31913.  
  31914. typedef struct Point3D Point3D;
  31915. æC 
  31916.  
  31917. æKY Point2D
  31918. æFc Graf3D.h
  31919. æT struct
  31920. æD struct Point2D {
  31921.     Fixed x;
  31922.     Fixed y;
  31923. };
  31924.  
  31925. typedef struct Point2D Point2D;
  31926. æC 
  31927.  
  31928. æKY Port3D
  31929. Port3DPtr
  31930. Port3DHandle
  31931. æFc Graf3D.h
  31932. æT struct
  31933. æD struct Port3D {
  31934.     GrafPtr grPort;
  31935.     Rect viewRect;
  31936.     Fixed xLeft;
  31937.     Fixed yTop;
  31938.     Fixed xRight;
  31939.     Fixed yBottom;
  31940.     Point3D pen;
  31941.     Point3D penPrime;
  31942.     Point3D eye;
  31943.     Fixed hSize;
  31944.     Fixed vSize;
  31945.     Fixed hCenter;
  31946.     Fixed vCenter;
  31947.     Fixed xCotan;
  31948.     Fixed yCotan;
  31949.     char filler;
  31950.     char ident;
  31951.     XfMatrix xForm;
  31952. };
  31953.  
  31954. typedef struct Port3D Port3D;
  31955. typedef Port3D *Port3DPtr, **Port3DHandle;
  31956.  
  31957. æC 
  31958.  
  31959. æKY InitGrf3d
  31960. æFc Graf3D.h
  31961. æT Function
  31962. æD pascal void InitGrf3d(Port3DHandle port); 
  31963. æDT InitGrf3d((Port3DHandle) port);
  31964. æC 
  31965.  
  31966. æKY Open3DPort
  31967. æFc Graf3D.h
  31968. æT Function
  31969. æD pascal void Open3DPort(Port3DPtr port); 
  31970. æDT Open3DPort((Port3DPtr) port);
  31971. æC 
  31972.  
  31973. æKY SetPort3D
  31974. æFc Graf3D.h
  31975. æT Function
  31976. æD pascal void SetPort3D(Port3DPtr port); 
  31977. æDT SetPort3D((Port3DPtr) port);
  31978. æC     SetPort sets the grafPort indicated by gp to be the current port.
  31979. The global pointer thePort always points to the current port. All
  31980. QuickDraw drawing routines affect the bitMap thePort^.portBits and use
  31981. the local coordinate system of thePort^. Note that OpenPort and
  31982. InitPort do a SetPort to the given port.
  31983.  
  31984. Warning:
  31985.  
  31986.     Never do a SetPort to a port that has not been opened
  31987.     with OpenPort.
  31988.  
  31989.     Each port possesses its own pen and text characteristics which
  31990. remain unchanged when the port is not selected as the current port.
  31991.  
  31992. æKY GetPort3D
  31993. æFc Graf3D.h
  31994. æT Function
  31995. æD pascal void GetPort3D(Port3DPtr *port); 
  31996. æDT GetPort3D((Port3DPtr *) port);
  31997. æC     GetPort returns a pointer to the current grafPort. If you have a
  31998. program that draws into more than one grafPort, it's extremely useful 
  31999. to have each procedure save the current grafPort (with GetPort), set
  32000. its own grafPort, do drawing or calculations, and then restore the
  32001. previous grafPort (with SetPort). The pointer to the current grafPort
  32002. is also available through the global pointer thePort, but you may
  32003. prefer to use GetPort for better readability of your program text. For
  32004. example, a procedure could do a GetPort (savePort) before setting its
  32005. own grafPort and a SetPort (savePort) afterwards to restore the
  32006. previous port.
  32007.  
  32008. æKY MoveTo2D
  32009. æFc Graf3D.h
  32010. æT Function
  32011. æD pascal void MoveTo2D(Fixed x,Fixed y); 
  32012. æDT MoveTo2D((Fixed) x,(Fixed) y);
  32013. æC     MoveTo moves the pen to location  (h,v) in the local coordinates of
  32014. the current grafPort. No drawing is performed.
  32015.  
  32016. æKY MoveTo3D
  32017. æFc Graf3D.h
  32018. æT Function
  32019. æD pascal void MoveTo3D(Fixed x,Fixed y,Fixed z); 
  32020. æDT MoveTo3D((Fixed) x,(Fixed) y,(Fixed) z);
  32021. æC 
  32022.  
  32023. æKY LineTo2D
  32024. æFc Graf3D.h
  32025. æT Function
  32026. æD pascal void LineTo2D(Fixed x,Fixed y); 
  32027. æDT LineTo2D((Fixed) x,(Fixed) y);
  32028. æC     This procedure draws a line to the location that is a distance of dh
  32029. horizontally and dv vertically from the current pen location; it calls
  32030. LineTo(h+dh,v+dv), where (h,v) is the current location. The positive
  32031. directions are to the right and down. The pen location becomes the
  32032. coordinates of the end of the line after the line is drawn. See the
  32033. general discussion of drawing.
  32034.  
  32035.     If a region or polygon is open and being formed, its outline is
  32036. infinitely thin and is not affected by the pnSize, pnMode, or pnPat.
  32037. (See OpenRgn and OpenPoly.)
  32038.  
  32039. æKY Move2D
  32040. æFc Graf3D.h
  32041. æT Function
  32042. æD pascal void Move2D(Fixed dx,Fixed dy); 
  32043. æDT Move2D((Fixed) dx,(Fixed) dy);
  32044. æC 
  32045.  
  32046. æKY Move3D
  32047. æFc Graf3D.h
  32048. æT Function
  32049. æD pascal void Move3D(Fixed dx,Fixed dy,Fixed dz); 
  32050. æDT Move3D((Fixed) dx,(Fixed) dy,(Fixed) dz);
  32051. æC 
  32052.  
  32053. æKY Line2D
  32054. æFc Graf3D.h
  32055. æT Function
  32056. æD pascal void Line2D(Fixed dx,Fixed dy); 
  32057. æDT Line2D((Fixed) dx,(Fixed) dy);
  32058. æC 
  32059.  
  32060. æKY Line3D
  32061. æFc Graf3D.h
  32062. æT Function
  32063. æD pascal void Line3D(Fixed dx,Fixed dy,Fixed dz); 
  32064. æDT Line3D((Fixed) dx,(Fixed) dy,(Fixed) dz);
  32065. æC 
  32066.  
  32067. æKY ViewPort
  32068. æFc Graf3D.h
  32069. æT Function
  32070. æD pascal void ViewPort(const Rect *r); 
  32071. æDT ViewPort((const Rect *) r);
  32072. æC 
  32073.  
  32074. æKY LookAt
  32075. æFc Graf3D.h
  32076. æT Function
  32077. æD pascal void LookAt(Fixed left,Fixed top,Fixed right,Fixed bottom); 
  32078. æDT LookAt((Fixed) left,(Fixed) top,(Fixed) right,(Fixed) bottom);
  32079. æC 
  32080.  
  32081. æKY ViewAngle
  32082. æFc Graf3D.h
  32083. æT Function
  32084. æD pascal void ViewAngle(Fixed angle); 
  32085. æDT ViewAngle((Fixed) angle);
  32086. æC 
  32087.  
  32088. æKY Identity
  32089. æFc Graf3D.h
  32090. æT Function
  32091. æD pascal void Identity(void); 
  32092. æDT Identity()(void);
  32093. æC 
  32094.  
  32095. æKY Scale
  32096. æFc Graf3D.h
  32097. æT Function
  32098. æD pascal void Scale(Fixed xFactor,Fixed yFactor,Fixed zFactor); 
  32099. æDT Scale((Fixed) xFactor,(Fixed) yFactor,(Fixed) zFactor);
  32100. æC 
  32101.  
  32102. æKY Translate
  32103. æFc Graf3D.h
  32104. æT Function
  32105. æD pascal void Translate(Fixed dx,Fixed dy,Fixed dz); 
  32106. æDT Translate((Fixed) dx,(Fixed) dy,(Fixed) dz);
  32107. æC 
  32108.  
  32109. æKY Pitch
  32110. æFc Graf3D.h
  32111. æT Function
  32112. æD pascal void Pitch(Fixed xAngle); 
  32113. æDT Pitch((Fixed) xAngle);
  32114. æC 
  32115.  
  32116. æKY Yaw
  32117. æFc Graf3D.h
  32118. æT Function
  32119. æD pascal void Yaw(Fixed yAngle); 
  32120. æDT Yaw((Fixed) yAngle);
  32121. æC 
  32122.  
  32123. æKY Roll
  32124. æFc Graf3D.h
  32125. æT Function
  32126. æD pascal void Roll(Fixed zAngle); 
  32127. æDT Roll((Fixed) zAngle);
  32128. æC 
  32129.  
  32130. æKY Skew
  32131. æFc Graf3D.h
  32132. æT Function
  32133. æD pascal void Skew(Fixed zAngle); 
  32134. æDT Skew((Fixed) zAngle);
  32135. æC 
  32136.  
  32137. æKY Transform
  32138. æFc Graf3D.h
  32139. æT Function
  32140. æD pascal void Transform(const Point3D *src,Point3D *dst); 
  32141. æDT Transform((const Point3D *) src,(Point3D *) dst);
  32142. æC 
  32143.  
  32144. æKY Clip3D
  32145. æFc Graf3D.h
  32146. æT Function
  32147. æD pascal short Clip3D(const Point3D *src1,const Point3D *src2,Point *dst1,
  32148.     Point *dst2); 
  32149. æDT short myVariable = Clip3D((const Point3D *) src1,(const Point3D *) src2,(Point *) dst1,(
  32150.     Point) * dst2);
  32151. æC 
  32152.  
  32153. æKY SetPt3D
  32154. æFc Graf3D.h
  32155. æT Function
  32156. æD pascal void SetPt3D(Point3D *pt3D,Fixed x,Fixed y,Fixed z); 
  32157. æDT SetPt3D((Point3D *) pt3D,(Fixed) x,(Fixed) y,(Fixed) z);
  32158. æC     SetPt assigns two integer coordinates to a variable of type Point.
  32159.  
  32160. æKY SetPt2D
  32161. æFc Graf3D.h
  32162. æT Function
  32163. æD pascal void SetPt2D(Point2D *pt2D,Fixed x,Fixed y); 
  32164. æDT SetPt2D((Point2D *) pt2D,(Fixed) x,(Fixed) y);
  32165. æC 
  32166.  
  32167. æKY LineTo3D
  32168. æFc Graf3D.h
  32169. æT Function
  32170. æD pascal void LineTo3D(Fixed x,Fixed y,Fixed z); 
  32171. æDT LineTo3D((Fixed) x,(Fixed) y,(Fixed) z);
  32172. æC 
  32173.  
  32174.  
  32175. æKY HyperXCmd.h
  32176. æKL BoolToStr
  32177. EvalExpr
  32178. ExtToStr
  32179. GetFieldByID
  32180. GetFieldByName
  32181. GetFieldByNum
  32182. GetGlobal
  32183. LongToStr
  32184. NumToHex
  32185. NumToStr
  32186. PasToZero
  32187. ReturnToPas
  32188. ScanToReturn
  32189. ScanToZero
  32190. SendCardMessage
  32191. SendHCMessage
  32192. SetFieldByID
  32193. SetFieldByName
  32194. SetFieldByNum
  32195. SetGlobal
  32196. StringEqual
  32197. StringLength
  32198. StringMatch
  32199. StrToBool
  32200. StrToExt
  32201. StrToLong
  32202. StrToNum
  32203. ZeroBytes
  32204. ZeroToPas
  32205.  
  32206. XCmdBlock
  32207. XCmdPtr
  32208. xreqBoolToStr
  32209. xreqEvalExpr
  32210. xreqExtToStr
  32211. xreqGetFieldByID
  32212. xreqGetFieldByName
  32213. xreqGetFieldByNum
  32214. xreqGetGlobal
  32215. xreqLongToStr
  32216. xreqNumToHex
  32217. xreqNumToStr
  32218. xreqPasToZero
  32219. xreqReturnToPas
  32220. xreqScanToReturn
  32221. xreqScanToZero
  32222. xreqSendCardMessage
  32223. xreqSendHCMessage
  32224. xreqSetFieldByID
  32225. xreqSetFieldByName
  32226. xreqSetFieldByNum
  32227. xreqSetGlobal
  32228. xreqStringEqual
  32229. xreqStringLength
  32230. xreqStringMatch
  32231. xreqStrToBool
  32232. xreqStrToExt
  32233. xreqStrToLong
  32234. xreqStrToNum
  32235. xreqZeroBytes
  32236. xreqZeroToPas
  32237. xresFail
  32238. xresNotImp
  32239. xresSucc
  32240.  
  32241. æKY xresSucc
  32242. æFc HyperXCmd.h
  32243. æT #define
  32244. æD 
  32245. /* result codes */
  32246.  
  32247. #define xresSucc 0
  32248. æC 
  32249.  
  32250. æKY xresFail
  32251. æFc HyperXCmd.h
  32252. æT #define
  32253. æD #define xresFail 1
  32254. æC 
  32255.  
  32256. æKY xresNotImp
  32257. æFc HyperXCmd.h
  32258. æT #define
  32259. æD #define xresNotImp 2
  32260. æC 
  32261.  
  32262. æKY xreqSendCardMessage
  32263. æFc HyperXCmd.h
  32264. æT #define
  32265. æD 
  32266. /* request codes */
  32267.  
  32268. #define xreqSendCardMessage 1
  32269. æC 
  32270.  
  32271. æKY xreqEvalExpr
  32272. æFc HyperXCmd.h
  32273. æT #define
  32274. æD #define xreqEvalExpr 2
  32275. æC 
  32276.  
  32277. æKY xreqStringLength
  32278. æFc HyperXCmd.h
  32279. æT #define
  32280. æD #define xreqStringLength 3
  32281. æC 
  32282.  
  32283. æKY xreqStringMatch
  32284. æFc HyperXCmd.h
  32285. æT #define
  32286. æD #define xreqStringMatch 4
  32287. æC 
  32288.  
  32289. æKY xreqSendHCMessage
  32290. æFc HyperXCmd.h
  32291. æT #define
  32292. æD #define xreqSendHCMessage 5
  32293. æC 
  32294.  
  32295. æKY xreqZeroBytes
  32296. æFc HyperXCmd.h
  32297. æT #define
  32298. æD #define xreqZeroBytes 6
  32299. æC 
  32300.  
  32301. æKY xreqPasToZero
  32302. æFc HyperXCmd.h
  32303. æT #define
  32304. æD #define xreqPasToZero 7
  32305. æC 
  32306.  
  32307. æKY xreqZeroToPas
  32308. æFc HyperXCmd.h
  32309. æT #define
  32310. æD #define xreqZeroToPas 8
  32311. æC 
  32312.  
  32313. æKY xreqStrToLong
  32314. æFc HyperXCmd.h
  32315. æT #define
  32316. æD #define xreqStrToLong 9
  32317. æC 
  32318.  
  32319. æKY xreqStrToNum
  32320. æFc HyperXCmd.h
  32321. æT #define
  32322. æD #define xreqStrToNum 10
  32323. æC 
  32324.  
  32325. æKY xreqStrToBool
  32326. æFc HyperXCmd.h
  32327. æT #define
  32328. æD #define xreqStrToBool 11
  32329. æC 
  32330.  
  32331. æKY xreqStrToExt
  32332. æFc HyperXCmd.h
  32333. æT #define
  32334. æD #define xreqStrToExt 12
  32335. æC 
  32336.  
  32337. æKY xreqLongToStr
  32338. æFc HyperXCmd.h
  32339. æT #define
  32340. æD #define xreqLongToStr 13
  32341. æC 
  32342.  
  32343. æKY xreqNumToStr
  32344. æFc HyperXCmd.h
  32345. æT #define
  32346. æD #define xreqNumToStr 14
  32347. æC 
  32348.  
  32349. æKY xreqNumToHex
  32350. æFc HyperXCmd.h
  32351. æT #define
  32352. æD #define xreqNumToHex 15
  32353. æC 
  32354.  
  32355. æKY xreqBoolToStr
  32356. æFc HyperXCmd.h
  32357. æT #define
  32358. æD #define xreqBoolToStr 16
  32359. æC 
  32360.  
  32361. æKY xreqExtToStr
  32362. æFc HyperXCmd.h
  32363. æT #define
  32364. æD #define xreqExtToStr 17
  32365. æC 
  32366.  
  32367. æKY xreqGetGlobal
  32368. æFc HyperXCmd.h
  32369. æT #define
  32370. æD #define xreqGetGlobal 18
  32371. æC 
  32372.  
  32373. æKY xreqSetGlobal
  32374. æFc HyperXCmd.h
  32375. æT #define
  32376. æD #define xreqSetGlobal 19
  32377. æC 
  32378.  
  32379. æKY xreqGetFieldByName
  32380. æFc HyperXCmd.h
  32381. æT #define
  32382. æD #define xreqGetFieldByName 20
  32383. æC 
  32384.  
  32385. æKY xreqGetFieldByNum
  32386. æFc HyperXCmd.h
  32387. æT #define
  32388. æD #define xreqGetFieldByNum 21
  32389. æC 
  32390.  
  32391. æKY xreqGetFieldByID
  32392. æFc HyperXCmd.h
  32393. æT #define
  32394. æD #define xreqGetFieldByID 22
  32395. æC 
  32396.  
  32397. æKY xreqSetFieldByName
  32398. æFc HyperXCmd.h
  32399. æT #define
  32400. æD #define xreqSetFieldByName 23
  32401. æC 
  32402.  
  32403. æKY xreqSetFieldByNum
  32404. æFc HyperXCmd.h
  32405. æT #define
  32406. æD #define xreqSetFieldByNum 24
  32407. æC 
  32408.  
  32409. æKY xreqSetFieldByID
  32410. æFc HyperXCmd.h
  32411. æT #define
  32412. æD #define xreqSetFieldByID 25
  32413. æC 
  32414.  
  32415. æKY xreqStringEqual
  32416. æFc HyperXCmd.h
  32417. æT #define
  32418. æD #define xreqStringEqual 26
  32419. æC 
  32420.  
  32421. æKY xreqReturnToPas
  32422. æFc HyperXCmd.h
  32423. æT #define
  32424. æD #define xreqReturnToPas 27
  32425. æC 
  32426.  
  32427. æKY xreqScanToReturn
  32428. æFc HyperXCmd.h
  32429. æT #define
  32430. æD #define xreqScanToReturn 28
  32431. æC 
  32432.  
  32433. æKY xreqScanToZero
  32434. æFc HyperXCmd.h
  32435. æT #define
  32436. æD #define xreqScanToZero 39 /* Yes, really 39!*/
  32437. æC 
  32438.  
  32439. æKY XCmdBlock
  32440. XCmdPtr
  32441. æFc HyperXCmd.h
  32442. æT struct
  32443. æD struct XCmdBlock {
  32444.     short paramCount;
  32445.     Handle params[16];
  32446.     Handle returnValue;
  32447.     Boolean passFlag;
  32448.     void (*entryPoint)(); /*to call back to HyperCard*/
  32449.     short request;
  32450.     short result;
  32451.     long inArgs[8];
  32452.     long outArgs[4];
  32453. };
  32454.  
  32455. typedef struct XCmdBlock XCmdBlock;
  32456. typedef XCmdBlock *XCmdPtr;
  32457.  
  32458. æC 
  32459.  
  32460. æKY SendCardMessage
  32461. æFc HyperXCmd.h
  32462. æT Function
  32463. æD pascal void SendCardMessage(XCmdPtr paramPtr,const Str255 msg); 
  32464. æDT SendCardMessage((XCmdPtr) paramPtr,(const Str255) msg);
  32465. æC 
  32466.  
  32467. æKY SendHCMessage
  32468. æFc HyperXCmd.h
  32469. æT Function
  32470. æD pascal void SendHCMessage(XCmdPtr paramPtr,const Str255 msg); 
  32471. æDT SendHCMessage((XCmdPtr) paramPtr,(const Str255) msg);
  32472. æC 
  32473.  
  32474. æKY GetGlobal
  32475. æFc HyperXCmd.h
  32476. æT Function
  32477. æD pascal Handle GetGlobal(XCmdPtr paramPtr,const Str255 globName); 
  32478. æDT Handle myVariable = GetGlobal((XCmdPtr) paramPtr,(const Str255) globName);
  32479. æC 
  32480.  
  32481. æKY SetGlobal
  32482. æFc HyperXCmd.h
  32483. æT Function
  32484. æD pascal void SetGlobal(XCmdPtr paramPtr,const Str255 globName,Handle globValue); 
  32485. æDT SetGlobal((XCmdPtr) paramPtr,(const Str255) globName,(Handle) globValue);
  32486. æC 
  32487.  
  32488. æKY GetFieldByID
  32489. æFc HyperXCmd.h
  32490. æT Function
  32491. æD pascal Handle GetFieldByID(XCmdPtr paramPtr,Boolean cardFieldFlag,short fieldID); 
  32492. æDT Handle myVariable = GetFieldByID((XCmdPtr) paramPtr,(Boolean) cardFieldFlag,(short) fieldID);
  32493. æC 
  32494.  
  32495. æKY GetFieldByName
  32496. æFc HyperXCmd.h
  32497. æT Function
  32498. æD pascal Handle GetFieldByName(XCmdPtr paramPtr,Boolean cardFieldFlag,const Str255 fieldName); 
  32499. æDT Handle myVariable = GetFieldByName((XCmdPtr) paramPtr,(Boolean) cardFieldFlag,(const Str255) fieldName);
  32500. æC 
  32501.  
  32502. æKY GetFieldByNum
  32503. æFc HyperXCmd.h
  32504. æT Function
  32505. æD pascal Handle GetFieldByNum(XCmdPtr paramPtr,Boolean cardFieldFlag,short fieldNum); 
  32506. æDT Handle myVariable = GetFieldByNum((XCmdPtr) paramPtr,(Boolean) cardFieldFlag,(short) fieldNum);
  32507. æC 
  32508.  
  32509. æKY SetFieldByID
  32510. æFc HyperXCmd.h
  32511. æT Function
  32512. æD pascal void SetFieldByID(XCmdPtr paramPtr,Boolean cardFieldFlag,short fieldID,
  32513.     Handle fieldVal); 
  32514. æDT SetFieldByID((XCmdPtr) paramPtr,(Boolean) cardFieldFlag,(short) fieldID,()
  32515.     Handle fieldVal);
  32516. æC 
  32517.  
  32518. æKY SetFieldByName
  32519. æFc HyperXCmd.h
  32520. æT Function
  32521. æD pascal void SetFieldByName(XCmdPtr paramPtr,Boolean cardFieldFlag,const Str255 fieldName,
  32522.     Handle fieldVal); 
  32523. æDT SetFieldByName((XCmdPtr) paramPtr,(Boolean) cardFieldFlag,(const Str255) fieldName,()
  32524.     Handle fieldVal);
  32525. æC 
  32526.  
  32527. æKY SetFieldByNum
  32528. æFc HyperXCmd.h
  32529. æT Function
  32530. æD pascal void SetFieldByNum(XCmdPtr paramPtr,Boolean cardFieldFlag,short fieldNum,
  32531.     Handle fieldVal); 
  32532. æDT SetFieldByNum((XCmdPtr) paramPtr,(Boolean) cardFieldFlag,(short) fieldNum,()
  32533.     Handle fieldVal);
  32534. æC 
  32535.  
  32536. æKY BoolToStr
  32537. æFc HyperXCmd.h
  32538. æT Function
  32539. æD pascal void BoolToStr(XCmdPtr paramPtr,Boolean bool,Str255 str); 
  32540. æDT BoolToStr((XCmdPtr) paramPtr,(Boolean) bool,(Str255) str);
  32541. æC 
  32542.  
  32543. æKY ExtToStr
  32544. æFc HyperXCmd.h
  32545. æT Function
  32546. æD pascal void ExtToStr(XCmdPtr paramPtr,extended *num,Str255 str); 
  32547. æDT ExtToStr((XCmdPtr) paramPtr,(extended *) num,(Str255) str);
  32548. æC 
  32549.  
  32550. æKY LongToStr
  32551. æFc HyperXCmd.h
  32552. æT Function
  32553. æD pascal void LongToStr(XCmdPtr paramPtr,long posNum,Str255 str); 
  32554. æDT LongToStr((XCmdPtr) paramPtr,(long) posNum,(Str255) str);
  32555. æC 
  32556.  
  32557. æKY NumToStr
  32558. æFc HyperXCmd.h
  32559. æT Function
  32560. æD pascal void NumToStr(XCmdPtr paramPtr,long num,Str255 str); 
  32561. æDT NumToStr((XCmdPtr) paramPtr,(long) num,(Str255) str);
  32562. æC 
  32563.  
  32564. æKY NumToHex
  32565. æFc HyperXCmd.h
  32566. æT Function
  32567. æD pascal void NumToHex(XCmdPtr paramPtr,long num,short nDigits,Str255 str); 
  32568. æDT NumToHex((XCmdPtr) paramPtr,(long) num,(short) nDigits,(Str255) str);
  32569. æC 
  32570.  
  32571. æKY StrToBool
  32572. æFc HyperXCmd.h
  32573. æT Function
  32574. æD pascal Boolean StrToBool(XCmdPtr paramPtr,const Str255 str); 
  32575. æDT Boolean myVariable = StrToBool((XCmdPtr) paramPtr,(const Str255) str);
  32576. æC 
  32577.  
  32578. æKY StrToExt
  32579. æFc HyperXCmd.h
  32580. æT Function
  32581. æD pascal extended StrToExt(XCmdPtr paramPtr,const Str255 str); 
  32582. æDT extended myVariable = StrToExt((XCmdPtr) paramPtr,(const Str255) str);
  32583. æC 
  32584.  
  32585. æKY StrToLong
  32586. æFc HyperXCmd.h
  32587. æT Function
  32588. æD pascal long StrToLong(XCmdPtr paramPtr,const Str255 str); 
  32589. æDT long myVariable = StrToLong((XCmdPtr) paramPtr,(const Str255) str);
  32590. æC 
  32591.  
  32592. æKY StrToNum
  32593. æFc HyperXCmd.h
  32594. æT Function
  32595. æD pascal long StrToNum(XCmdPtr paramPtr,const Str255 str); 
  32596. æDT long myVariable = StrToNum((XCmdPtr) paramPtr,(const Str255) str);
  32597. æC 
  32598.  
  32599. æKY PasToZero
  32600. æFc HyperXCmd.h
  32601. æT Function
  32602. æD pascal Handle PasToZero(XCmdPtr paramPtr,const Str255 str); 
  32603. æDT Handle myVariable = PasToZero((XCmdPtr) paramPtr,(const Str255) str);
  32604. æC 
  32605.  
  32606. æKY ZeroToPas
  32607. æFc HyperXCmd.h
  32608. æT Function
  32609. æD pascal void ZeroToPas(XCmdPtr paramPtr,char *zeroStr,Str255 pasStr); 
  32610. æDT ZeroToPas((XCmdPtr) paramPtr,(char *) zeroStr,(Str255) pasStr);
  32611. æC 
  32612.  
  32613. æKY EvalExpr
  32614. æFc HyperXCmd.h
  32615. æT Function
  32616. æD pascal Handle EvalExpr(XCmdPtr paramPtr,const Str255 expr); 
  32617. æDT Handle myVariable = EvalExpr((XCmdPtr) paramPtr,(const Str255) expr);
  32618. æC 
  32619.  
  32620. æKY ReturnToPas
  32621. æFc HyperXCmd.h
  32622. æT Function
  32623. æD pascal void ReturnToPas(XCmdPtr paramPtr,Ptr zeroStr,Str255 pasStr); 
  32624. æDT ReturnToPas((XCmdPtr) paramPtr,(Ptr) zeroStr,(Str255) pasStr);
  32625. æC 
  32626.  
  32627. æKY ScanToReturn
  32628. æFc HyperXCmd.h
  32629. æT Function
  32630. æD pascal void ScanToReturn(XCmdPtr paramPtr,Ptr *scanPtr); 
  32631. æDT ScanToReturn((XCmdPtr) paramPtr,(Ptr *) scanPtr);
  32632. æC 
  32633.  
  32634. æKY ScanToZero
  32635. æFc HyperXCmd.h
  32636. æT Function
  32637. æD pascal void ScanToZero(XCmdPtr paramPtr,Ptr *scanPtr); 
  32638. æDT ScanToZero((XCmdPtr) paramPtr,(Ptr *) scanPtr);
  32639. æC 
  32640.  
  32641. æKY StringEqual
  32642. æFc HyperXCmd.h
  32643. æT Function
  32644. æD pascal Boolean StringEqual(XCmdPtr paramPtr,const Str255 str1,const Str255 str2); 
  32645. æDT Boolean myVariable = StringEqual((XCmdPtr) paramPtr,(const Str255) str1,(const Str255) str2);
  32646. æC 
  32647.  
  32648. æKY StringMatch
  32649. æFc HyperXCmd.h
  32650. æT Function
  32651. æD pascal Ptr StringMatch(XCmdPtr paramPtr,const Str255 pattern,Ptr target); 
  32652. æDT Ptr myVariable = StringMatch((XCmdPtr) paramPtr,(const Str255) pattern,(Ptr) target);
  32653. æC 
  32654.  
  32655. æKY StringLength
  32656. æFc HyperXCmd.h
  32657. æT Function
  32658. æD pascal long StringLength(XCmdPtr paramPtr,char *strPtr); 
  32659. æDT long myVariable = StringLength((XCmdPtr) paramPtr,(char *) strPtr);
  32660. æC 
  32661.  
  32662. æKY ZeroBytes
  32663. æFc HyperXCmd.h
  32664. æT Function
  32665. æD pascal void ZeroBytes(XCmdPtr paramPtr,Ptr dstPtr,long longCount); 
  32666. æDT ZeroBytes((XCmdPtr) paramPtr,(Ptr) dstPtr,(long) longCount);
  32667. æC 
  32668.  
  32669.  
  32670. æKY IOCtl.h
  32671. ioctl
  32672. æFc IOCtl.h
  32673. æC 
  32674. ioctl    
  32675.  
  32676. FIOBUFSIZE    FIOINTERACTIVE    FIOSETEOF    TIOSPORT
  32677. FIODUPFD      FIOLSEEK          TIOFLUSH      
  32678. FIOFNAME      FIOREFNUM         TIOGPORT    
  32679.  
  32680.                           Synopsis
  32681.  
  32682. #include <IOCtl.h>
  32683. int ioctl(int fildes, unsigned int cmd, long *arg);
  32684.  
  32685.  
  32686.                            Description
  32687.  
  32688. The ioctl; function communicates with a file’s device driver by sending
  32689. control information, requesting status information, or both. 
  32690. Parameter cmd indicates which device-specific operations ioctl must perform.
  32691. Here are the control values.
  32692. Value of cmd     Description
  32693.  
  32694. FIOINTERACTIVE   The ioctl function returns 0 if the device is interactive; 
  32695.                  if not, it returns –1 and errno is set to EINVAL. 
  32696.                  Parameter arg is ignored.
  32697. FIOBUFSIZE   The ioctl function returns, in bytes, the optimal buffer size
  32698.              for this device; the buffer size is returned in a long pointed 
  32699.              to by arg. If the device has no default buffer size, ioctl 
  32700.              returns –1 and errno is set to EINVAL.
  32701. FIOFNAME     The ioctl function stores the filename associated with fildes 
  32702.              in a C string pointed to by arg. It returns –1 if the filename 
  32703.              exceeds 255 characters [E2BIG]. Use only for a program running 
  32704.              as an MPW tool.
  32705. FIOREFNUM    The ioctl function returns the Macintosh file reference number 
  32706.              associated with fildes; the reference number is returned in the 
  32707.              short pointed to by arg. If the fildes is not open on a Macintosh 
  32708.              file (such as the console device), ioctl returns –1.
  32709. FIOSETEOF    The ioctl function sets the logical end-of-file specified in the 
  32710.              long parameter arg. The value of arg is the new size of the file, 
  32711.              in bytes. This command can be used to reduce or increase the size 
  32712.              of the open file. The current file pointer is not affected unless 
  32713.              the file size is set below it.
  32714. TIOFLUSH     Used only for the console device and other terminal devices. 
  32715.              The ioctlfunction returns –1 if fildes is not a terminal device. 
  32716.              TIOFLUSH tells the device driver to throw away unread terminal 
  32717.              input. Parameter arg is ignored.
  32718.  
  32719.                           Diagnostics
  32720.  
  32721. If an error has occurred, a value of –1 is returned and errno is set to  
  32722. indicate the error.
  32723.  
  32724.                            Note
  32725.  
  32726. For cmd values FIOINTERACTIVE and FIOBUFSIZE, a function return of –1 is  
  32727. a meaningful response, not an error. For FIOINTERACTIVE, errno is set to  
  32728. EINVAL for devices that are not interactive. For FIOBUFSIZE, errno is set  
  32729. to EINVAL for devices that have no default buffering.
  32730. The cmd values FIOLSEEK and FIODUPFD are reserved for operating-system use.
  32731. If you set the console GrafPort with TIOSPORT, do not deallocate the storage  
  32732. for that port; the console device is written to by the exit function as your  
  32733. application terminates.
  32734.  
  32735. The console device ioctl control values TIOGPORT and TIOSPORT are no longer  
  32736. supported. It is no longer possible to perform direct I/O to a user-supplied  
  32737. GrafPort.
  32738.  
  32739.                            Warning
  32740.  
  32741. FIOREFNUM lets you do Macintosh I/O operations, such as Allocate, that are  
  32742. not available through ioctl. Do not close or modify the file pointer by using  
  32743. the reference number.
  32744.  
  32745. See also
  32746. fcntl, faccess, ferror
  32747.  
  32748. æKY FIOBUFSIZE
  32749. æFc IOCtl.h
  32750. æD #define FIOBUFSIZE   (('f'<<8)|03) /*Return optimal buffer size*/
  32751.  
  32752.  
  32753. æKY FIODUPFD
  32754. æFc IOCtl.h
  32755. æD #define FIODUPFD (('f'<<8)|01) /*3rd arg is min new fd number*/
  32756.  
  32757.  
  32758. æKY FIOFNAME
  32759. æFc IOCtl.h
  32760. æD #define FIOFNAME (('f'<<8)|04) /*Return filename*/
  32761.  
  32762.  
  32763. æKY FIOINTERACTIVE
  32764. æFc IOCtl.h
  32765. æD #define FIOINTERACTIVE   (('f'<<8)|02) /*If device is interactive*/
  32766.  
  32767.  
  32768. æKY FIOLSEEK
  32769. æFc IOCtl.h
  32770. æD #define FIOLSEEK (('f'<<8)|00) /*3rd arg is a _SeekType (below)*/
  32771.  
  32772.  
  32773. æKY FIOREFNUM
  32774. æFc IOCtl.h
  32775. æD #define FIOREFNUM    (('f'<<8)|05) /*Return fs refnum*/
  32776.  
  32777.  
  32778. æKY FIOSETEOF
  32779. æFc IOCtl.h
  32780. æD #define FIOSETEOF    (('f'<<8)|06) /*Set file length*/
  32781.  
  32782.  
  32783. æKY TIOFLUSH
  32784. æFc IOCtl.h
  32785. æD #define TIOFLUSH (('t'<<8)|00)
  32786.  
  32787.  
  32788. æKY TIOGPORT
  32789. æFc IOCtl.h
  32790. æD #define TIOGPORT (('t'<<8)|02)
  32791.  
  32792.  
  32793. æKY TIOSPORT
  32794. æFc IOCtl.h
  32795. æD #define TIOSPORT (('t'<<8)|01)
  32796.  
  32797.  
  32798.  
  32799. æKY ioctlæ
  32800. æDT 
  32801. int myVariable = ioctl((int) fildes, (unsigned int) cmd, (long *)arg);
  32802.  
  32803. æKY Limits.h
  32804. æFc Limits.h
  32805. æD                            Synopsis
  32806.  
  32807. #define CHAR_BIT     8
  32808. #define MB_LEN_MAX   2
  32809. #define CHAR_MI      (-128)
  32810. #define CHAR_MAX     127
  32811. #define SCHAR_MI     (-128)
  32812. #define SCHAR_MAX    127
  32813. #define UCHAR_MAX    255U
  32814. #define SHRT_MI      (-32768)
  32815. #define SHRT_MAX     32767
  32816. #define USHRT_MAX    65535U
  32817. #define INT_MI       (-2147483648)
  32818. #define INT_MAX      2147483647
  32819. #define UINT_MAX     4294967295U
  32820. #define LONG_MI      (-2147483648)
  32821. #define LONG_MAX     2147483647
  32822. #define ULONG_MAX    4294967295U
  32823.  
  32824. æC
  32825.                                 Description
  32826.  
  32827. The header <Limits.h> specifies the number of bits in a byte, 
  32828. and the minimum and maximum values for the integral types 
  32829. (that is, char, signed char, unsigned char, short, unsigned short, 
  32830. int, unsigned int, long, and unsigned long).
  32831.  There are 8 bits in a byte.
  32832.  Type char is signed, and is 8 bits.
  32833.  Types signed char and unsigned char are 8 bits.
  32834.  Types short and unsigned short are 16 bits.
  32835.  Types int, unsigned int, long and unsigned long are 32 bits.
  32836.  
  32837.  
  32838. æKY Lists.h
  32839. æKL LActivate
  32840. LAddColumn
  32841. LAddRow
  32842. LAddToCell
  32843. LAutoScroll
  32844. lcellsize
  32845. LCellSize
  32846. LClick
  32847. lclick
  32848. LClrCell
  32849. LDelColumn
  32850. LDelRow
  32851. LDispose
  32852. LDoDraw
  32853. ldraw
  32854. LDraw
  32855. LFind
  32856. LGetCell
  32857. LGetSelect
  32858. LLastClick
  32859. LNew
  32860. lnew
  32861. LNextCell
  32862. LRect
  32863. LScroll
  32864. LSearch
  32865. LSetCell
  32866. LSetSelect
  32867. LSize
  32868. LUpdate
  32869.  
  32870. Cell
  32871. DataArray
  32872. lCloseMsg
  32873. lDoHAutoscroll
  32874. lDoVAutoscroll
  32875. lDrawMsg
  32876. lExtendDrag
  32877. lHiliteMsg
  32878. lInitMsg
  32879. ListHandle
  32880. ListPtr
  32881. ListRec
  32882. lNoDisjoint
  32883. lNoExtend
  32884. lNoNilHilite
  32885. lNoRect
  32886. lOnlyOne
  32887. lUseSense
  32888. SearchProcPtr
  32889.  
  32890. æKY lDoVAutoscroll
  32891. æFc Lists.h
  32892. æT #define
  32893. æD #define lDoVAutoscroll 2
  32894. æC 
  32895.  
  32896. æKY lDoHAutoscroll
  32897. æFc Lists.h
  32898. æT #define
  32899. æD #define lDoHAutoscroll 1
  32900. æC 
  32901.  
  32902. æKY lOnlyOne
  32903. æFc Lists.h
  32904. æT #define
  32905. æD #define lOnlyOne -128
  32906. æC 
  32907.  
  32908. æKY lExtendDrag
  32909. æFc Lists.h
  32910. æT #define
  32911. æD #define lExtendDrag 64
  32912. æC 
  32913.  
  32914. æKY lNoDisjoint
  32915. æFc Lists.h
  32916. æT #define
  32917. æD #define lNoDisjoint 32
  32918. æC 
  32919.  
  32920. æKY lNoExtend
  32921. æFc Lists.h
  32922. æT #define
  32923. æD #define lNoExtend 16
  32924. æC 
  32925.  
  32926. æKY lNoRect
  32927. æFc Lists.h
  32928. æT #define
  32929. æD #define lNoRect 8
  32930. æC 
  32931.  
  32932. æKY lUseSense
  32933. æFc Lists.h
  32934. æT #define
  32935. æD #define lUseSense 4
  32936. æC 
  32937.  
  32938. æKY lNoNilHilite
  32939. æFc Lists.h
  32940. æT #define
  32941. æD #define lNoNilHilite 2
  32942. æC 
  32943.  
  32944. æKY lInitMsg
  32945. æFc Lists.h
  32946. æT #define
  32947. æD #define lInitMsg 0
  32948. æC 
  32949.  
  32950. æKY lDrawMsg
  32951. æFc Lists.h
  32952. æT #define
  32953. æD #define lDrawMsg 1
  32954. æC 
  32955.  
  32956. æKY lHiliteMsg
  32957. æFc Lists.h
  32958. æT #define
  32959. æD #define lHiliteMsg 2
  32960. æC 
  32961.  
  32962. æKY lCloseMsg
  32963. æFc Lists.h
  32964. æT #define
  32965. æD #define lCloseMsg 3
  32966. æC 
  32967.  
  32968. æKY Cell
  32969. æFc Lists.h
  32970. æT typedef
  32971. æD typedef Point Cell;
  32972. æC 
  32973.  
  32974. æKY DataArray
  32975. æFc Lists.h
  32976. æT typedef
  32977. æD typedef char DataArray[32001],*DataPtr,**DataHandle;
  32978. æC 
  32979.  
  32980. æKY SearchProcPtr
  32981. æFc Lists.h
  32982. æT typedef
  32983. æD typedef pascal short (*SearchProcPtr)(Ptr aPtr, Ptr bPtr, short aLen, short bLen);
  32984. æC 
  32985.  
  32986. æKY ListRec
  32987. ListPtr
  32988. ListHandle
  32989. æFc Lists.h
  32990. æT struct
  32991. æD struct ListRec {
  32992.     Rect rView;
  32993.     GrafPtr port;
  32994.     Point indent;
  32995.     Point cellSize;
  32996.     Rect visible;
  32997.     ControlHandle vScroll;
  32998.     ControlHandle hScroll;
  32999.     char selFlags;
  33000.     Boolean lActive;
  33001.     char lReserved;
  33002.     char listFlags;
  33003.     long clikTime;
  33004.     Point clikLoc;
  33005.     Point mouseLoc;
  33006.     ProcPtr lClikLoop;
  33007.     Cell lastClick;
  33008.     long refCon;
  33009.     Handle listDefProc;
  33010.     Handle userHandle;
  33011.     Rect dataBounds;
  33012.     DataHandle cells;
  33013.     short maxIndex;
  33014.     short cellArray[1];
  33015. };
  33016.  
  33017. typedef struct ListRec ListRec;
  33018. typedef ListRec *ListPtr, **ListHandle;
  33019.  
  33020. æC  
  33021. »The List Record Data Structure
  33022.  
  33023. The exact data structure of a list record is as follows:
  33024.  
  33025. TYPE  Cell       = Point;
  33026.       DataArray  = PACKED ARRAY [0..32000] OF CHAR;
  33027.       DataPtr    = ^DataArray;
  33028.       DataHandle = ^DataPtr;
  33029.       ListRec    = RECORD
  33030.                      rView:        Rect;           {list's display rectangle}
  33031.                      port:         GrafPtr;        {list's grafPort}
  33032.                      indent:       Point;          {indent distance}
  33033.                      cellSize:     Point;          {cell size}
  33034.                      visible:      Rect;           {boundary of visible cells}
  33035.                      vScroll:      ControlHandle;  {vertical scroll bar}
  33036.                      hScroll:      ControlHandle;  {horizontal scroll bar}
  33037.                      selFlags:     SignedByte;     {selection flags}
  33038.                      lActive:      BOOLEAN;        {TRUE if active}
  33039.                      lReserved:    SignedByte;     {reserved}
  33040.                      listFlags:    SignedByte;     {automatic scrolling flags}
  33041.                      clikTime:     LONGINT;        {time of last click}
  33042.                      clikLoc:      Point;          {position of last click}
  33043.                      mouseLoc:     Point;          {current mouse location}
  33044.                      lClikLoop:    Ptr;            {routine for LClick}
  33045.                      lastClick:    Cell;           {last cell clicked}
  33046.                      refCon:       LONGINT;        {list's reference value}
  33047.                      listDefProc:  Handle;         {list definition procedure}
  33048.                      userHandle:   Handle;         {additional storage}
  33049.                      dataBounds:   Rect;           {boundary of cells allocated}
  33050.                      cells:        DataHandle;     {cell data}
  33051.                      maxIndex:     INTEGER;        {used internally}
  33052.                      cellArray:    ARRAY [1..1] OF INTEGER    {offsets to data}
  33053.                    END;
  33054.  
  33055.       ListPtr    = ^ListRec;
  33056.       ListHandle = ^ListPtr;
  33057.  
  33058. RView is the rectangle, given in the local coordinates of the grafPort, in which the
  33059. list is displayed. Room for scroll bars is not included in this rectangle. If the
  33060. list has scroll bars and is to fill the entire window, rView should be 15 points
  33061. smaller in each dimension than the grafPort.
  33062.  
  33063. Port is the grafPort used by the list; it’s set to the port of the window specified
  33064. when the list is created. Indent is the distance in pixels that the list definition
  33065. procedure should indent from the topLeft of the cell when drawing the contents. The
  33066. default value for indent is 0, but it can be set by the list definition procedure.
  33067.  
  33068. CellSize is the size of a cell in pixels. If it’s not specified when the list is
  33069. created, a default cell size is set. CellSize.v is set to the ascent plus descent
  33070. plus leading of the port’s font, and cellSize.h is set to
  33071.  
  33072.   (rView.right – rView.left) DIV (dataBounds.right – dataBounds.left)
  33073.  
  33074. A cell is a box in which a list element is displayed. Cells are identified by their
  33075. column and row numbers. In Figure 1, for instance, the highlighted cell is in column
  33076. 1, row 2.
  33077.  
  33078. Cells are declared as points, using the Point data type simply as a way of specifying
  33079. the column and row number of a cell. Similarly, visible and dataBounds use the Rect
  33080. data type to specify a rectangular set of cells as two diagonally opposite cell
  33081. coordinates (rather than two diagonally opposite points in the local coordinates of a
  33082. grafPort).
  33083.  
  33084. DataBounds is the boundary of the cells currently allocated, specified by row and
  33085. column. The list in Figure 1 (assuming the entire list is visible) has seventeen rows
  33086. and five columns of cells. DataBounds for this list can be represented, using the
  33087. QuickDraw rectangle notation (left,top)(right,bottom), as (0,0)(5,17). Notice that
  33088. the column and row specified for the bottom right of dataBounds are 1 greater in each
  33089. dimension than the column and row number of the bottom right cell. Thus, you can test
  33090. to see if a cell is a valid cell within the boundary of a list using the statement:
  33091.  
  33092.   IF PtInRect(c,myList^^.dataBounds) THEN...
  33093.  
  33094. The visible rectangle reflects which cells are currently within the visible part of
  33095. the list; it’s calculated by the List Manager according to the values you specify for
  33096. rView, dataBounds, and cellSize when you create the list.
  33097. (Visible.topLeft is the row and column of the top left visible cell; visible.botRight
  33098. is 1 greater in both dimensions than the row and column of the bottom right visible
  33099. cell.) For example, if only four cells—row 2, column 0; row 2, column 1; row 3,
  33100. column 0; and row 3, column 1—are visible, the visible rectangle is (0,2)(2,4). You
  33101. can test to see if a cell is visible using the statement:
  33102.  
  33103.   IF PtInRect(c,myList^^.visible) THEN...
  33104.  
  33105. •••Refer to Figure 1.•••
  33106.  
  33107. Figure 1–A Sample List
  33108.  
  33109. SelFlags contains selection flags for the List Manager. It’s initialized to 0; with
  33110. this setting, the List Manager selects cells according to the Macintosh User Interface
  33111. Guidelines. The meaning of these flags is explained below in the section “Cell Selection
  33112. Algorithm”. The listFlags field contains automatic scrolling flags; the List Manager
  33113. sets these flags automatically when you specify scroll bars. There are predefined
  33114. constants that let you set or test the status of the corresponding bits:
  33115.  
  33116. CONST  lDoVAutoScroll = 2;    {set to allow automatic vertical scrolling}
  33117.        lDoHAutoScroll = 1;    {set to allow automatic horizontal scrolling}
  33118.  
  33119. ClikLoc is the position of the last mouse click in local coordinates; you can use it
  33120. in the list definition procedure to get the position within the cell. LClikLoop is a
  33121. pointer to the routine to be called during the LClick function, as described later.
  33122. LastClick contains the cell coordinates of the last cell clicked in.
  33123.  
  33124. RefCon is the list’s reference value field, which the application may store into and
  33125. access for any purpose. In addition, the application may use the field userHandle to
  33126. store a handle to an additional storage area.
  33127.  
  33128. CellArray contains offsets to the cell data. For each list element, this includes the
  33129. bit indicating whether the cell is selected or not.
  33130.  
  33131. »The LClikLoop Field
  33132.  
  33133. The lClikLoop field of a list record lets you specify a routine that will be called
  33134. repeatedly (by the LClick function, described below) as long as the mouse button is
  33135. held down within the rView rectangle or its scroll bars.
  33136.  
  33137. Note:  The LClick function performs automatic scrolling if the mouse is
  33138.        dragged outside the visible rectangle, so there’s no need to write
  33139.        a list click loop routine to do automatic scrolling.
  33140.  
  33141. The list click loop routine has no parameters and returns a Boolean value. You could
  33142. declare a list click loop routine named MyClikLoop like this:
  33143.  
  33144. FUNCTION MyClikLoop :  BOOLEAN;
  33145.  
  33146. The function should return TRUE. You must put a pointer to your list click loop
  33147. routine in the lClikLoop field of the list record so that the List Manager will call
  33148. your routine.
  33149.  
  33150. Warning:  Returning FALSE from your list click loop routine tells the
  33151.           LClick function that the mouse button has been released, which
  33152.           aborts LClick.
  33153.  
  33154. Assembly-language note:  Your routine should set register D0 to 1; returning
  33155.                          0 in register D0 aborts LClick. For your convenience,
  33156.                          register D5 contains the current mouse location.
  33157.  
  33158. æKY lnew
  33159. æFc Lists.h
  33160. æT Function
  33161. æD ListHandle lnew(Rect *rView,Rect *dataBounds,Point *cSize,short theProc,
  33162.     WindowPtr theWindow,Boolean drawIt,Boolean hasGrow,Boolean scrollHoriz,
  33163.     Boolean scrollVert); 
  33164. æDT ListHandle myVariable = lnew((Rect *) rView,(Rect *) dataBounds,(Point *) cSize,(short) theProc,()
  33165.     WindowPtr theWindow,(Boolean) drawIt,(Boolean) hasGrow,(Boolean) scrollHoriz,()
  33166.     Boolean scrollVert);
  33167. æRI IV-270
  33168. æC 
  33169. Call LNew to create a new list. It returns a handle to the new list. The list’s
  33170. grafPort is set to theWindow’s port. If drawIt is FALSE, the list is not displayed.
  33171.  
  33172. RView specifies, in the local coordinates of theWindow, the rectangle in which the
  33173. list will be displayed. (Remember that this doesn’t include space for scroll bars. If
  33174. the list, including scroll bars, is to fill the entire window, rView should be 15
  33175. points smaller in each dimension than theWindow’s portRect.)
  33176.  
  33177. DataBounds is the rectangle for specifying the initial array dimensions of the list.
  33178. For example to preallocate space for a list that’s 5 cells across by 10 cells down,
  33179. you should set dataBounds to (0,0)(5,10). If you want to allocate the space for a
  33180. one-column list, set dataBounds to (0,0)(1,0) and use LAddRow.
  33181.  
  33182. CSize.h and cSize.v are the desired height and width of each cell in pixels; if
  33183. they’re not specified, a default cell size is calculated (as described above).
  33184.  
  33185. TheProc is the resource ID of your list definition procedure; for a text-only list,
  33186. pass 0 and the default list definition procedure (about 150 bytes in size) will be
  33187. used. The list definition procedure is called to initialize itself after all other
  33188. list record fields have been initialized; thus, it can use any of the values in the
  33189. list record (or set particular fields, such as the indent distance).
  33190.  
  33191. If hasGrow is TRUE, the scroll bars are sized so that there’s room for a size box in
  33192. the standard position. It’s up to the program to display the size box
  33193. (using the Window Manager procedure DrawGrowIcon). If scrollHoriz is TRUE, a horizontal
  33194. scroll bar is placed immediately below rView and all horizontal scrolling functions
  33195. are implemented. If scrollVert is TRUE, a vertical scroll bar is placed immediately
  33196. to the right of rView and all vertical scrolling functions are implemented.
  33197.  
  33198. The visible rectangle is set to contain as many cells of cSize (or the default) as
  33199. will fit into rView. If the cells do not fit exactly into rView, the visible rectangle
  33200. is rounded up to the nearest cell. Scrolling will always allow all cells to be fully
  33201. displayed. The selection flags are set to 0, and the active flag is set to TRUE.
  33202.  
  33203. Note:  Scrolling looks best if rView is a multiple of cSize.v in height.
  33204.  
  33205. Assembly-language note:  You can invoke each of the List Manager routines
  33206.                          with a macro that has the same name as the routine
  33207.                          preceded by an underscore. These macros expand to
  33208.                          invoke to trap macro _Pack 0. The package determines
  33209.                          which routine to execute from a routine selector, an
  33210.                          integer that’s passed to it in a word on the stack.
  33211.                          The routine selectors are as follows:
  33212.  
  33213.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  33214.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  33215.                            lAddRow     .EQU    8    lClick       .EQU    24
  33216.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  33217.                            lDelColumn  .EQU    32   lNew         .EQU    68
  33218.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  33219.                            lDispose    .EQU    40   lRect        .EQU    76
  33220.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  33221.                            lDraw       .EQU    48   lSearch      .EQU    84
  33222.                            lFind       .EQU    52   lSetCell     .EQU    88
  33223.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  33224.                            lGetSelect  .EQU    60   lSize        .EQU    96
  33225.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  33226.  
  33227. æKY LNew
  33228. æFc Lists.h
  33229. æT Function
  33230. æTN $A9E7
  33231. æD pascal ListHandle LNew(const Rect *rView,const Rect *dataBounds,Point cSize,
  33232.     short theProc,WindowPtr theWindow,Boolean drawIt,Boolean hasGrow,Boolean scrollHoriz,
  33233.     Boolean scrollVert)
  33234.     = {0x3F3C,0x0044,0xA9E7}; 
  33235. æDT ListHandle myVariable = LNew((const Rect *) rView,(const Rect *) dataBounds,(Point) cSize,()
  33236.     short theProc,(WindowPtr) theWindow,(Boolean) drawIt,(Boolean) hasGrow,(Boolean) scrollHoriz,()
  33237.     Boolean scrollVert);
  33238. æRI IV-270
  33239. æC 
  33240. Call LNew to create a new list. It returns a handle to the new list. The list’s
  33241. grafPort is set to theWindow’s port. If drawIt is FALSE, the list is not displayed.
  33242.  
  33243. RView specifies, in the local coordinates of theWindow, the rectangle in which the
  33244. list will be displayed. (Remember that this doesn’t include space for scroll bars. If
  33245. the list, including scroll bars, is to fill the entire window, rView should be 15
  33246. points smaller in each dimension than theWindow’s portRect.)
  33247.  
  33248. DataBounds is the rectangle for specifying the initial array dimensions of the list.
  33249. For example to preallocate space for a list that’s 5 cells across by 10 cells down,
  33250. you should set dataBounds to (0,0)(5,10). If you want to allocate the space for a
  33251. one-column list, set dataBounds to (0,0)(1,0) and use LAddRow.
  33252.  
  33253. CSize.h and cSize.v are the desired height and width of each cell in pixels; if
  33254. they’re not specified, a default cell size is calculated (as described above).
  33255.  
  33256. TheProc is the resource ID of your list definition procedure; for a text-only list,
  33257. pass 0 and the default list definition procedure (about 150 bytes in size) will be
  33258. used. The list definition procedure is called to initialize itself after all other
  33259. list record fields have been initialized; thus, it can use any of the values in the
  33260. list record (or set particular fields, such as the indent distance).
  33261.  
  33262. If hasGrow is TRUE, the scroll bars are sized so that there’s room for a size box in
  33263. the standard position. It’s up to the program to display the size box
  33264. (using the Window Manager procedure DrawGrowIcon). If scrollHoriz is TRUE, a horizontal
  33265. scroll bar is placed immediately below rView and all horizontal scrolling functions
  33266. are implemented. If scrollVert is TRUE, a vertical scroll bar is placed immediately
  33267. to the right of rView and all vertical scrolling functions are implemented.
  33268.  
  33269. The visible rectangle is set to contain as many cells of cSize (or the default) as
  33270. will fit into rView. If the cells do not fit exactly into rView, the visible rectangle
  33271. is rounded up to the nearest cell. Scrolling will always allow all cells to be fully
  33272. displayed. The selection flags are set to 0, and the active flag is set to TRUE.
  33273.  
  33274. Note:  Scrolling looks best if rView is a multiple of cSize.v in height.
  33275.  
  33276. Assembly-language note:  You can invoke each of the List Manager routines
  33277.                          with a macro that has the same name as the routine
  33278.                          preceded by an underscore. These macros expand to
  33279.                          invoke to trap macro _Pack 0. The package determines
  33280.                          which routine to execute from a routine selector, an
  33281.                          integer that’s passed to it in a word on the stack.
  33282.                          The routine selectors are as follows:
  33283.  
  33284.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  33285.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  33286.                            lAddRow     .EQU    8    lClick       .EQU    24
  33287.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  33288.                            lDelColumn  .EQU    32   lNew         .EQU    68
  33289.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  33290.                            lDispose    .EQU    40   lRect        .EQU    76
  33291.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  33292.                            lDraw       .EQU    48   lSearch      .EQU    84
  33293.                            lFind       .EQU    52   lSetCell     .EQU    88
  33294.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  33295.                            lGetSelect  .EQU    60   lSize        .EQU    96
  33296.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  33297.  
  33298. æKY LDispose
  33299. æFc Lists.h
  33300. æT Function
  33301. æTN $A9E7
  33302. æD pascal void LDispose(ListHandle lHandle)
  33303.     = {0x3F3C,0x0028,0xA9E7}; 
  33304. æDT LDispose((ListHandle) lHandle);
  33305. æRI IV-271
  33306. æC 
  33307. Call LDispose when you are through using a list. It issues a close call to the list
  33308. definition procedure, and calls the Memory Manager procedure DisposHandle for the
  33309. data handle, the Control Manager procedure DisposeControl for both scroll bars (if
  33310. they’re there), and DisposHandle for the list record.
  33311.  
  33312. Note:  Calling LDispose is much faster than deleting one row at a time.
  33313.  
  33314. Assembly-language note:  You can invoke each of the List Manager routines
  33315.                          with a macro that has the same name as the routine
  33316.                          preceded by an underscore. These macros expand to
  33317.                          invoke to trap macro _Pack 0. The package determines
  33318.                          which routine to execute from a routine selector, an
  33319.                          integer that’s passed to it in a word on the stack.
  33320.                          The routine selectors are as follows:
  33321.  
  33322.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  33323.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  33324.                            lAddRow     .EQU    8    lClick       .EQU    24
  33325.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  33326.                            lDelColumn  .EQU    32   lNew         .EQU    68
  33327.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  33328.                            lDispose    .EQU    40   lRect        .EQU    76
  33329.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  33330.                            lDraw       .EQU    48   lSearch      .EQU    84
  33331.                            lFind       .EQU    52   lSetCell     .EQU    88
  33332.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  33333.                            lGetSelect  .EQU    60   lSize        .EQU    96
  33334.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  33335.  
  33336. æKY LAddColumn
  33337. æFc Lists.h
  33338. æT Function
  33339. æTN $A9E7
  33340. æD pascal short LAddColumn(short count,short colNum,ListHandle lHandle)
  33341.     = {0x3F3C,0x0004,0xA9E7}; 
  33342. æDT short myVariable = LAddColumn((short) count,(short) colNum,(ListHandle) lHandle);
  33343. æRI IV-271
  33344. æC 
  33345. LAddColumn inserts into the given list the number of columns specified by the count
  33346. parameter, starting at the column specified by colNum. Column numbers that are greater
  33347. than or equal to colNum are increased by count. If colNum is not within dataBounds,
  33348. new last columns are added. The number of the first added column is returned and
  33349. dataBounds.right is increased by count. All cells added are empty. If there are no
  33350. cells (because dataBounds.top = dataBounds.bottom), no cells are added, but dataBounds
  33351. is still extended. If drawing is on and the added columns (which are empty) are
  33352. visible, the list and its scroll bars are updated.
  33353.  
  33354. Assembly-language note:  You can invoke each of the List Manager routines
  33355.                          with a macro that has the same name as the routine
  33356.                          preceded by an underscore. These macros expand to
  33357.                          invoke to trap macro _Pack 0. The package determines
  33358.                          which routine to execute from a routine selector, an
  33359.                          integer that’s passed to it in a word on the stack.
  33360.                          The routine selectors are as follows:
  33361.  
  33362.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  33363.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  33364.                            lAddRow     .EQU    8    lClick       .EQU    24
  33365.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  33366.                            lDelColumn  .EQU    32   lNew         .EQU    68
  33367.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  33368.                            lDispose    .EQU    40   lRect        .EQU    76
  33369.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  33370.                            lDraw       .EQU    48   lSearch      .EQU    84
  33371.                            lFind       .EQU    52   lSetCell     .EQU    88
  33372.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  33373.                            lGetSelect  .EQU    60   lSize        .EQU    96
  33374.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  33375.  
  33376. æKY LAddRow
  33377. æFc Lists.h
  33378. æT Function
  33379. æTN $A9E7
  33380. æD pascal short LAddRow(short count,short rowNum,ListHandle lHandle)
  33381.     = {0x3F3C,0x0008,0xA9E7}; 
  33382. æDT short myVariable = LAddRow((short) count,(short) rowNum,(ListHandle) lHandle);
  33383. æRI IV-271
  33384. æC 
  33385. LAddRow inserts the number of rows specified by the count parameter, starting at the
  33386. row specified by rowNum. Row numbers that are greater than or equal to rowNum are
  33387. increased by count. If rowNum is not within dataBounds, new last rows are added. The
  33388. number of the first added row is returned, and dataBounds.bottom is increased by
  33389. count. All cells added are empty. If there are no cells
  33390. (because dataBounds.left = dataBounds.right), no cells are added, but dataBounds is
  33391. still extended. If drawing is on and the added rows (which are empty) are visible,
  33392. the list and its scroll bars are updated.
  33393.  
  33394. Assembly-language note:  You can invoke each of the List Manager routines
  33395.                          with a macro that has the same name as the routine
  33396.                          preceded by an underscore. These macros expand to
  33397.                          invoke to trap macro _Pack 0. The package determines
  33398.                          which routine to execute from a routine selector, an
  33399.                          integer that’s passed to it in a word on the stack.
  33400.                          The routine selectors are as follows:
  33401.  
  33402.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  33403.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  33404.                            lAddRow     .EQU    8    lClick       .EQU    24
  33405.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  33406.                            lDelColumn  .EQU    32   lNew         .EQU    68
  33407.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  33408.                            lDispose    .EQU    40   lRect        .EQU    76
  33409.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  33410.                            lDraw       .EQU    48   lSearch      .EQU    84
  33411.                            lFind       .EQU    52   lSetCell     .EQU    88
  33412.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  33413.                            lGetSelect  .EQU    60   lSize        .EQU    96
  33414.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  33415.  
  33416. æKY LDelColumn
  33417. æFc Lists.h
  33418. æT Function
  33419. æTN $A9E7
  33420. æD pascal void LDelColumn(short count,short colNum,ListHandle lHandle)
  33421.     = {0x3F3C,0x0020,0xA9E7}; 
  33422. æDT LDelColumn((short) count,(short) colNum,(ListHandle) lHandle);
  33423. æRI IV-271
  33424. æC 
  33425. LDelColumn deletes the number of columns specified by the count parameter, starting
  33426. with the column specified by colNum. Column numbers that are greater than colNum are
  33427. decreased by count. If colNum is not within dataBounds, nothing is done. DataBounds.right
  33428. is decreased by count. If drawing is on and the deleted columns were visible, the
  33429. list and its scroll bars are updated.
  33430.  
  33431. If count is 0, or
  33432.  
  33433.   colNum = dataBounds.left AND count > = dataBounds.right – dataBounds.left
  33434.  
  33435. all the data in the list is quickly deleted, dataBounds.right is set to dataBounds.left,
  33436. and the number of rows is left unchanged.
  33437.  
  33438. Assembly-language note:  You can invoke each of the List Manager routines
  33439.                          with a macro that has the same name as the routine
  33440.                          preceded by an underscore. These macros expand to
  33441.                          invoke to trap macro _Pack 0. The package determines
  33442.                          which routine to execute from a routine selector, an
  33443.                          integer that’s passed to it in a word on the stack.
  33444.                          The routine selectors are as follows:
  33445.  
  33446.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  33447.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  33448.                            lAddRow     .EQU    8    lClick       .EQU    24
  33449.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  33450.                            lDelColumn  .EQU    32   lNew         .EQU    68
  33451.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  33452.                            lDispose    .EQU    40   lRect        .EQU    76
  33453.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  33454.                            lDraw       .EQU    48   lSearch      .EQU    84
  33455.                            lFind       .EQU    52   lSetCell     .EQU    88
  33456.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  33457.                            lGetSelect  .EQU    60   lSize        .EQU    96
  33458.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  33459.  
  33460. æKY LDelRow
  33461. æFc Lists.h
  33462. æT Function
  33463. æTN $A9E7
  33464. æD pascal void LDelRow(short count,short rowNum,ListHandle lHandle)
  33465.     = {0x3F3C,0x0024,0xA9E7}; 
  33466. æDT LDelRow((short) count,(short) rowNum,(ListHandle) lHandle);
  33467. æRI IV-272
  33468. æC 
  33469. LDelRow deletes the number of rows specified by the count parameter, starting with
  33470. the row specified by rowNum. Row numbers that are greater than rowNum are decreased
  33471. by count. If rowNum is not within dataBounds, nothing is done. DataBounds.bottom is
  33472. decreased by count. If drawing is on and the deleted rows were visible, the list and
  33473. its scroll bars are updated.
  33474.  
  33475. If count is 0, or
  33476.  
  33477.   rowNum = dataBounds.top AND count > = dataBounds.bottom – dataBounds.top
  33478.  
  33479. all the data in the list is quickly deleted, dataBounds.bottom is set to dataBounds.top,
  33480. and the number of columns is left unchanged.
  33481.  
  33482. Assembly-language note:  You can invoke each of the List Manager routines
  33483.                          with a macro that has the same name as the routine
  33484.                          preceded by an underscore. These macros expand to
  33485.                          invoke to trap macro _Pack 0. The package determines
  33486.                          which routine to execute from a routine selector, an
  33487.                          integer that’s passed to it in a word on the stack.
  33488.                          The routine selectors are as follows:
  33489.  
  33490.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  33491.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  33492.                            lAddRow     .EQU    8    lClick       .EQU    24
  33493.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  33494.                            lDelColumn  .EQU    32   lNew         .EQU    68
  33495.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  33496.                            lDispose    .EQU    40   lRect        .EQU    76
  33497.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  33498.                            lDraw       .EQU    48   lSearch      .EQU    84
  33499.                            lFind       .EQU    52   lSetCell     .EQU    88
  33500.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  33501.                            lGetSelect  .EQU    60   lSize        .EQU    96
  33502.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  33503.  
  33504. æKY LGetSelect
  33505. æFc Lists.h
  33506. æT Function
  33507. æTN $A9E7
  33508. æD pascal Boolean LGetSelect(Boolean next,Cell *theCell,ListHandle lHandle)
  33509.     = {0x3F3C,0x003C,0xA9E7}; 
  33510. æDT Boolean myVariable = LGetSelect((Boolean) next,(Cell *) theCell,(ListHandle) lHandle);
  33511. æRI IV-273
  33512. æC 
  33513. If next is FALSE, LGetSelect returns TRUE if the specified cell is selected, or FALSE
  33514. if not. If next is TRUE, LGetSelect returns in c the cell coordinates of the next
  33515. selected cell in the row that is greater than or equal to theCell. If there are no
  33516. more cells in the row, it returns in theCell the cell coordinates of the next selected
  33517. cell in the next row. If there are no more rows, FALSE is returned.
  33518.  
  33519. Assembly-language note:  You can invoke each of the List Manager routines
  33520.                          with a macro that has the same name as the routine
  33521.                          preceded by an underscore. These macros expand to
  33522.                          invoke to trap macro _Pack 0. The package determines
  33523.                          which routine to execute from a routine selector, an
  33524.                          integer that’s passed to it in a word on the stack.
  33525.                          The routine selectors are as follows:
  33526.  
  33527.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  33528.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  33529.                            lAddRow     .EQU    8    lClick       .EQU    24
  33530.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  33531.                            lDelColumn  .EQU    32   lNew         .EQU    68
  33532.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  33533.                            lDispose    .EQU    40   lRect        .EQU    76
  33534.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  33535.                            lDraw       .EQU    48   lSearch      .EQU    84
  33536.                            lFind       .EQU    52   lSetCell     .EQU    88
  33537.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  33538.                            lGetSelect  .EQU    60   lSize        .EQU    96
  33539.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  33540.  
  33541. æKY LLastClick
  33542. æFc Lists.h
  33543. æT Function
  33544. æTN $A9E7
  33545. æD pascal Cell LLastClick(ListHandle lHandle)
  33546.     = {0x3F3C,0x0040,0xA9E7}; 
  33547. æDT Cell myVariable = LLastClick((ListHandle) lHandle);
  33548. æRI IV-273
  33549. æC 
  33550. LLastClick returns the cell coordinates of the last cell clicked in. If no cell has
  33551. been clicked in since LNew, the value returned (for both integers) is negative.
  33552.  
  33553. Note:  The value returned by this call is not the last cell double-clicked
  33554.        in, or the last cell selected, but merely the last cell clicked in.
  33555.  
  33556. Assembly-language note:  You can invoke each of the List Manager routines
  33557.                          with a macro that has the same name as the routine
  33558.                          preceded by an underscore. These macros expand to
  33559.                          invoke to trap macro _Pack 0. The package determines
  33560.                          which routine to execute from a routine selector, an
  33561.                          integer that’s passed to it in a word on the stack.
  33562.                          The routine selectors are as follows:
  33563.  
  33564.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  33565.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  33566.                            lAddRow     .EQU    8    lClick       .EQU    24
  33567.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  33568.                            lDelColumn  .EQU    32   lNew         .EQU    68
  33569.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  33570.                            lDispose    .EQU    40   lRect        .EQU    76
  33571.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  33572.                            lDraw       .EQU    48   lSearch      .EQU    84
  33573.                            lFind       .EQU    52   lSetCell     .EQU    88
  33574.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  33575.                            lGetSelect  .EQU    60   lSize        .EQU    96
  33576.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  33577.  
  33578. æKY LNextCell
  33579. æFc Lists.h
  33580. æT Function
  33581. æTN $A9E7
  33582. æD pascal Boolean LNextCell(Boolean hNext,Boolean vNext,Cell *theCell,ListHandle lHandle)
  33583.     = {0x3F3C,0x0048,0xA9E7}; 
  33584. æDT Boolean myVariable = LNextCell((Boolean) hNext,(Boolean) vNext,(Cell *) theCell,(ListHandle) lHandle);
  33585. æRI IV-274
  33586. æC 
  33587. Given a cell in theCell, LNextCell returns in theCell the next cell in the list. If
  33588. both hNext and vNext are TRUE, theCell is first advanced to the next cell in the row.
  33589. If there are no more cells in the row, theCell is set to the first cell in the next
  33590. row. If there are no more rows, FALSE is returned. If only hNext is TRUE, theCell is
  33591. advanced within the current row. If only vNext is TRUE, theCell is advanced within
  33592. the current column. FALSE is returned if there are no remaining cells in the row or
  33593. column.
  33594.  
  33595. Assembly-language note:  You can invoke each of the List Manager routines
  33596.                          with a macro that has the same name as the routine
  33597.                          preceded by an underscore. These macros expand to
  33598.                          invoke to trap macro _Pack 0. The package determines
  33599.                          which routine to execute from a routine selector, an
  33600.                          integer that’s passed to it in a word on the stack.
  33601.                          The routine selectors are as follows:
  33602.  
  33603.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  33604.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  33605.                            lAddRow     .EQU    8    lClick       .EQU    24
  33606.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  33607.                            lDelColumn  .EQU    32   lNew         .EQU    68
  33608.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  33609.                            lDispose    .EQU    40   lRect        .EQU    76
  33610.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  33611.                            lDraw       .EQU    48   lSearch      .EQU    84
  33612.                            lFind       .EQU    52   lSetCell     .EQU    88
  33613.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  33614.                            lGetSelect  .EQU    60   lSize        .EQU    96
  33615.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  33616.  
  33617. æKY LSearch
  33618. æFc Lists.h
  33619. æT Function
  33620. æTN $A9E7
  33621. æD pascal Boolean LSearch(Ptr dataPtr,short dataLen,SearchProcPtr searchProc,
  33622.     Cell *theCell,ListHandle lHandle)
  33623.     = {0x3F3C,0x0054,0xA9E7}; 
  33624. æDT Boolean myVariable = LSearch((Ptr) dataPtr,(short) dataLen,(SearchProcPtr) searchProc,(
  33625.     Cell) * theCell,(ListHandle) lHandle);
  33626. æRI IV-274 
  33627. æC 
  33628. LSearch searches for the first cell greater than or equal to theCell that contains
  33629. the specified data. If a cell containing matching data is found, the function result
  33630. TRUE is returned, and the cell coordinates are returned in theCell. If searchProc is
  33631. NIL, the International Utilities Package function IUMagIDString is called to compare
  33632. the specified data with the contents of each cell. If searchProc is not NIL, the
  33633. routine pointed to by searchProc is called.
  33634.  
  33635. Note:  Your searchProc should have the same parameters as the
  33636.        IUMagIDString function.
  33637.  
  33638. Assembly-language note:  You can invoke each of the List Manager routines
  33639.                          with a macro that has the same name as the routine
  33640.                          preceded by an underscore. These macros expand to
  33641.                          invoke to trap macro _Pack 0. The package determines
  33642.                          which routine to execute from a routine selector, an
  33643.                          integer that’s passed to it in a word on the stack.
  33644.                          The routine selectors are as follows:
  33645.  
  33646.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  33647.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  33648.                            lAddRow     .EQU    8    lClick       .EQU    24
  33649.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  33650.                            lDelColumn  .EQU    32   lNew         .EQU    68
  33651.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  33652.                            lDispose    .EQU    40   lRect        .EQU    76
  33653.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  33654.                            lDraw       .EQU    48   lSearch      .EQU    84
  33655.                            lFind       .EQU    52   lSetCell     .EQU    88
  33656.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  33657.                            lGetSelect  .EQU    60   lSize        .EQU    96
  33658.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  33659.  
  33660. æKY LSize
  33661. æFc Lists.h
  33662. æT Function
  33663. æTN $A9E7
  33664. æD pascal void LSize(short listWidth,short listHeight,ListHandle lHandle)
  33665.     = {0x3F3C,0x0060,0xA9E7}; 
  33666. æDT LSize((short) listWidth,(short) listHeight,(ListHandle) lHandle);
  33667. æRI IV-274 
  33668. æC 
  33669. You’ll usually call LSize immediately after the Window Manager procedure SizeWindow.
  33670. It causes the bottom right of the list to be adjusted so that the list is the width
  33671. and height indicated by listWidth and listHeight. The contents of the list and the
  33672. scroll bars are adjusted and redrawn as necessary. The values of listWidth and listHeight
  33673. do not include the scroll bars; for a list that entirely fills the window, listWidth
  33674. and listHeight should be 15 fewer pixels than the portRect if both scroll bars are
  33675. present.
  33676.  
  33677. Assembly-language note:  You can invoke each of the List Manager routines
  33678.                          with a macro that has the same name as the routine
  33679.                          preceded by an underscore. These macros expand to
  33680.                          invoke to trap macro _Pack 0. The package determines
  33681.                          which routine to execute from a routine selector, an
  33682.                          integer that’s passed to it in a word on the stack.
  33683.                          The routine selectors are as follows:
  33684.  
  33685.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  33686.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  33687.                            lAddRow     .EQU    8    lClick       .EQU    24
  33688.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  33689.                            lDelColumn  .EQU    32   lNew         .EQU    68
  33690.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  33691.                            lDispose    .EQU    40   lRect        .EQU    76
  33692.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  33693.                            lDraw       .EQU    48   lSearch      .EQU    84
  33694.                            lFind       .EQU    52   lSetCell     .EQU    88
  33695.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  33696.                            lGetSelect  .EQU    60   lSize        .EQU    96
  33697.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  33698.  
  33699. æKY LDoDraw
  33700. æFc Lists.h
  33701. æT Function
  33702. æTN $A9E7
  33703. æD pascal void LDoDraw(Boolean drawIt,ListHandle lHandle)
  33704.     = {0x3F3C,0x002C,0xA9E7}; 
  33705. æDT LDoDraw((Boolean) drawIt,(ListHandle) lHandle);
  33706. æRI IV-275 
  33707. æC 
  33708. LDoDraw sets the List Manager’s drawing mode to the state specified by drawIt. If
  33709. drawIt is TRUE, changes made by most List Manager calls will cause some sort of
  33710. drawing to take place. If drawIt is FALSE, all cell drawing is disabled.
  33711. (Two exceptions:  The scroll bars are still updated after LSize, and the scroll
  33712. arrows are still highlighted if the user clicks them.)
  33713.  
  33714. The recommended use of LDoDraw is to disable drawing while you’re building a list
  33715. (that is, adding rows or columns, setting or changing cell values, or setting default
  33716. selections). Once you’ve finished building the list, you should then re-enable drawing.
  33717. In general, drawing should be on while you’re in your event loop and dispatching
  33718. events to the List Manager.
  33719.  
  33720. Assembly-language note:  You can invoke each of the List Manager routines
  33721.                          with a macro that has the same name as the routine
  33722.                          preceded by an underscore. These macros expand to
  33723.                          invoke to trap macro _Pack 0. The package determines
  33724.                          which routine to execute from a routine selector, an
  33725.                          integer that’s passed to it in a word on the stack.
  33726.                          The routine selectors are as follows:
  33727.  
  33728.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  33729.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  33730.                            lAddRow     .EQU    8    lClick       .EQU    24
  33731.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  33732.                            lDelColumn  .EQU    32   lNew         .EQU    68
  33733.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  33734.                            lDispose    .EQU    40   lRect        .EQU    76
  33735.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  33736.                            lDraw       .EQU    48   lSearch      .EQU    84
  33737.                            lFind       .EQU    52   lSetCell     .EQU    88
  33738.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  33739.                            lGetSelect  .EQU    60   lSize        .EQU    96
  33740.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  33741.  
  33742. æKY LScroll
  33743. æFc Lists.h
  33744. æT Function
  33745. æTN $A9E7
  33746. æD pascal void LScroll(short dCols,short dRows,ListHandle lHandle)
  33747.     = {0x3F3C,0x0050,0xA9E7}; 
  33748. æDT LScroll((short) dCols,(short) dRows,(ListHandle) lHandle);
  33749. æRI IV-275 
  33750. æC 
  33751. LScroll scrolls the given list by the number of columns and rows specified in dCols
  33752. and dRows, either positively (down and to the right) or negatively (up and to the
  33753. left). Scrolling is pinned to the list’s dataBounds. If drawing is on, LScroll does
  33754. all necessary updating of the screen.
  33755.  
  33756. Assembly-language note:  You can invoke each of the List Manager routines
  33757.                          with a macro that has the same name as the routine
  33758.                          preceded by an underscore. These macros expand to
  33759.                          invoke to trap macro _Pack 0. The package determines
  33760.                          which routine to execute from a routine selector, an
  33761.                          integer that’s passed to it in a word on the stack.
  33762.                          The routine selectors are as follows:
  33763.  
  33764.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  33765.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  33766.                            lAddRow     .EQU    8    lClick       .EQU    24
  33767.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  33768.                            lDelColumn  .EQU    32   lNew         .EQU    68
  33769.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  33770.                            lDispose    .EQU    40   lRect        .EQU    76
  33771.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  33772.                            lDraw       .EQU    48   lSearch      .EQU    84
  33773.                            lFind       .EQU    52   lSetCell     .EQU    88
  33774.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  33775.                            lGetSelect  .EQU    60   lSize        .EQU    96
  33776.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  33777.  
  33778. æKY LAutoScroll
  33779. æFc Lists.h
  33780. æT Function
  33781. æTN $A9E7
  33782. æD pascal void LAutoScroll(ListHandle lHandle)
  33783.     = {0x3F3C,0x0010,0xA9E7}; 
  33784. æDT LAutoScroll((ListHandle) lHandle);
  33785. æRI IV-275
  33786. æC 
  33787. For the given list, LAutoScroll scrolls the list until the first selected cell is
  33788. visible. It automatically places the first selected cell in the top left corner of
  33789. the visible rectangle.
  33790.  
  33791. Assembly-language note:  You can invoke each of the List Manager routines
  33792.                          with a macro that has the same name as the routine
  33793.                          preceded by an underscore. These macros expand to
  33794.                          invoke to trap macro _Pack 0. The package determines
  33795.                          which routine to execute from a routine selector, an
  33796.                          integer that’s passed to it in a word on the stack.
  33797.                          The routine selectors are as follows:
  33798.  
  33799.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  33800.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  33801.                            lAddRow     .EQU    8    lClick       .EQU    24
  33802.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  33803.                            lDelColumn  .EQU    32   lNew         .EQU    68
  33804.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  33805.                            lDispose    .EQU    40   lRect        .EQU    76
  33806.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  33807.                            lDraw       .EQU    48   lSearch      .EQU    84
  33808.                            lFind       .EQU    52   lSetCell     .EQU    88
  33809.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  33810.                            lGetSelect  .EQU    60   lSize        .EQU    96
  33811.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  33812.  
  33813. æKY LUpdate
  33814. æFc Lists.h
  33815. æT Function
  33816. æTN ,$A9E7
  33817. æD pascal void LUpdate(RgnHandle theRgn,ListHandle lHandle)
  33818.     = {0x3F3C,0x0064,0xA9E7}; 
  33819. æDT LUpdate((RgnHandle) theRgn,(ListHandle) lHandle);
  33820. æRI IV-275
  33821. æC 
  33822. LUpdate should be called in response to an update event. TheRgn should be set to the
  33823. visRgn of the list’s port (for more details, see the BeginUpdate procedure in the
  33824. Window Manager chapter). It redraws any visible cells in lHandle that intersect
  33825. theRgn. It also redraws the controls, if necessary.
  33826.  
  33827. Assembly-language note:  You can invoke each of the List Manager routines
  33828.                          with a macro that has the same name as the routine
  33829.                          preceded by an underscore. These macros expand to
  33830.                          invoke to trap macro _Pack 0. The package determines
  33831.                          which routine to execute from a routine selector, an
  33832.                          integer that’s passed to it in a word on the stack.
  33833.                          The routine selectors are as follows:
  33834.  
  33835.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  33836.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  33837.                            lAddRow     .EQU    8    lClick       .EQU    24
  33838.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  33839.                            lDelColumn  .EQU    32   lNew         .EQU    68
  33840.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  33841.                            lDispose    .EQU    40   lRect        .EQU    76
  33842.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  33843.                            lDraw       .EQU    48   lSearch      .EQU    84
  33844.                            lFind       .EQU    52   lSetCell     .EQU    88
  33845.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  33846.                            lGetSelect  .EQU    60   lSize        .EQU    96
  33847.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  33848.  
  33849. æKY LActivate
  33850. æFc Lists.h
  33851. æT Function
  33852. æTN $A9E7
  33853. æD pascal void LActivate(Boolean act,ListHandle lHandle)
  33854.     = {0x3F3C,0x0000,0xA9E7}; 
  33855. æDT LActivate((Boolean) act,(ListHandle) lHandle);
  33856. æRI IV-276 
  33857. æC 
  33858. Call LActivate to activate or deactivate the list specified by lHandle (in response
  33859. to an activate event in the window containing the list). The act parameter should be
  33860. set to TRUE to activate the list, or FALSE to deactivate the list. LActivate highlights
  33861. or unhighlights the selections, and shows or hides the scroll bars (but not the size
  33862. box, if any).
  33863.  
  33864. Assembly-language note:  You can invoke each of the List Manager routines
  33865.                          with a macro that has the same name as the routine
  33866.                          preceded by an underscore. These macros expand to
  33867.                          invoke to trap macro _Pack 0. The package determines
  33868.                          which routine to execute from a routine selector, an
  33869.                          integer that’s passed to it in a word on the stack.
  33870.                          The routine selectors are as follows:
  33871.  
  33872.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  33873.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  33874.                            lAddRow     .EQU    8    lClick       .EQU    24
  33875.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  33876.                            lDelColumn  .EQU    32   lNew         .EQU    68
  33877.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  33878.                            lDispose    .EQU    40   lRect        .EQU    76
  33879.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  33880.                            lDraw       .EQU    48   lSearch      .EQU    84
  33881.                            lFind       .EQU    52   lSetCell     .EQU    88
  33882.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  33883.                            lGetSelect  .EQU    60   lSize        .EQU    96
  33884.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  33885.  
  33886. æKY LCellSize
  33887. æFc Lists.h
  33888. æT Function
  33889. æTN $A9E7
  33890. æD pascal void LCellSize(Point cSize,ListHandle lHandle)
  33891.     = {0x3F3C,0x0014,0xA9E7}; 
  33892. æDT LCellSize((Point) cSize,(ListHandle) lHandle);
  33893. æRI IV-273
  33894. æC 
  33895. LCellSize sets the cellSize field in the list record to cSize and updates the visible
  33896. rectangle to contain cells of this size. This command should be used only before any
  33897. cells have been drawn.
  33898.  
  33899. Assembly-language note:  You can invoke each of the List Manager routines
  33900.                          with a macro that has the same name as the routine
  33901.                          preceded by an underscore. These macros expand to
  33902.                          invoke to trap macro _Pack 0. The package determines
  33903.                          which routine to execute from a routine selector, an
  33904.                          integer that’s passed to it in a word on the stack.
  33905.                          The routine selectors are as follows:
  33906.  
  33907.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  33908.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  33909.                            lAddRow     .EQU    8    lClick       .EQU    24
  33910.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  33911.                            lDelColumn  .EQU    32   lNew         .EQU    68
  33912.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  33913.                            lDispose    .EQU    40   lRect        .EQU    76
  33914.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  33915.                            lDraw       .EQU    48   lSearch      .EQU    84
  33916.                            lFind       .EQU    52   lSetCell     .EQU    88
  33917.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  33918.                            lGetSelect  .EQU    60   lSize        .EQU    96
  33919.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  33920.  
  33921. æKY LClick
  33922. æFc Lists.h
  33923. æT Function
  33924. æTN $A9E7
  33925. æD pascal Boolean LClick(Point pt,short modifiers,ListHandle lHandle)
  33926.     = {0x3F3C,0x0018,0xA9E7}; 
  33927. æDT Boolean myVariable = LClick((Point) pt,(short) modifiers,(ListHandle) lHandle);
  33928. æRI IV-273
  33929. æC 
  33930. Call LClick when there is a mouse-down event in the destination rectangle or its
  33931. scroll bars. Pt is the mouse location in local coordinates. Modifiers is the modifiers
  33932. word from the event record. LHandle is the list to be tracked. The result is TRUE if
  33933. a double-click occurred (and the two clicks took place within the same cell).
  33934.  
  33935. LClick keeps control until the mouse is released; each time through its inner loop,
  33936. it calls the routine whose pointer is in the lClikLoop field of the list record.
  33937.  
  33938. If the mouse is in the visible rectangle, cells are selected according to the state
  33939. of the modifiers and the selection flags. If the mouse was in the cells but is dragged
  33940. outside the list’s rectangle, the list is auto-scrolled. If the mouse was in a control,
  33941. the control’s definition procedure is called to track the mouse. To discover which
  33942. cell was clicked in, use the LLastClick function.
  33943.  
  33944. Assembly-language note:  You can invoke each of the List Manager routines
  33945.                          with a macro that has the same name as the routine
  33946.                          preceded by an underscore. These macros expand to
  33947.                          invoke to trap macro _Pack 0. The package determines
  33948.                          which routine to execute from a routine selector, an
  33949.                          integer that’s passed to it in a word on the stack.
  33950.                          The routine selectors are as follows:
  33951.  
  33952.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  33953.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  33954.                            lAddRow     .EQU    8    lClick       .EQU    24
  33955.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  33956.                            lDelColumn  .EQU    32   lNew         .EQU    68
  33957.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  33958.                            lDispose    .EQU    40   lRect        .EQU    76
  33959.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  33960.                            lDraw       .EQU    48   lSearch      .EQU    84
  33961.                            lFind       .EQU    52   lSetCell     .EQU    88
  33962.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  33963.                            lGetSelect  .EQU    60   lSize        .EQU    96
  33964.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  33965.  
  33966. æKY LAddToCell
  33967. æFc Lists.h
  33968. æT Function
  33969. æTN $A9E7
  33970. æD pascal void LAddToCell(Ptr dataPtr,short dataLen,Cell theCell,ListHandle lHandle)
  33971.     = {0x3F3C,0x000C,0xA9E7}; 
  33972. æDT LAddToCell((Ptr) dataPtr,(short) dataLen,(Cell) theCell,(ListHandle) lHandle);
  33973. æRI IV-272
  33974. æC 
  33975. LAddToCell appends the data pointed to by dataPtr and of length dataLen to the cell
  33976. specified by theCell in lHandle. If drawing is off, you must turn drawing on and call
  33977. LDraw (or LUpdate) to display the cell’s new value.
  33978.  
  33979. Assembly-language note:  You can invoke each of the List Manager routines
  33980.                          with a macro that has the same name as the routine
  33981.                          preceded by an underscore. These macros expand to
  33982.                          invoke to trap macro _Pack 0. The package determines
  33983.                          which routine to execute from a routine selector, an
  33984.                          integer that’s passed to it in a word on the stack.
  33985.                          The routine selectors are as follows:
  33986.  
  33987.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  33988.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  33989.                            lAddRow     .EQU    8    lClick       .EQU    24
  33990.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  33991.                            lDelColumn  .EQU    32   lNew         .EQU    68
  33992.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  33993.                            lDispose    .EQU    40   lRect        .EQU    76
  33994.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  33995.                            lDraw       .EQU    48   lSearch      .EQU    84
  33996.                            lFind       .EQU    52   lSetCell     .EQU    88
  33997.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  33998.                            lGetSelect  .EQU    60   lSize        .EQU    96
  33999.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  34000.  
  34001. æKY LClrCell
  34002. æFc Lists.h
  34003. æT Function
  34004. æTN $A9E7
  34005. æD pascal void LClrCell(Cell theCell,ListHandle lHandle)
  34006.     = {0x3F3C,0x001C,0xA9E7}; 
  34007. æDT LClrCell((Cell) theCell,(ListHandle) lHandle);
  34008. æRI IV-272
  34009. æC 
  34010. LClrCell clears the contents of the specified cell (by setting the length to 0). If
  34011. theCell is not a valid cell, nothing is done. If drawing is off, you must turn drawing
  34012. on and call LDraw to display the cell’s new value (or simply call the Window Manager
  34013. procedure InvalRect).
  34014.  
  34015. Assembly-language note:  You can invoke each of the List Manager routines
  34016.                          with a macro that has the same name as the routine
  34017.                          preceded by an underscore. These macros expand to
  34018.                          invoke to trap macro _Pack 0. The package determines
  34019.                          which routine to execute from a routine selector, an
  34020.                          integer that’s passed to it in a word on the stack.
  34021.                          The routine selectors are as follows:
  34022.  
  34023.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  34024.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  34025.                            lAddRow     .EQU    8    lClick       .EQU    24
  34026.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  34027.                            lDelColumn  .EQU    32   lNew         .EQU    68
  34028.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  34029.                            lDispose    .EQU    40   lRect        .EQU    76
  34030.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  34031.                            lDraw       .EQU    48   lSearch      .EQU    84
  34032.                            lFind       .EQU    52   lSetCell     .EQU    88
  34033.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  34034.                            lGetSelect  .EQU    60   lSize        .EQU    96
  34035.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  34036.  
  34037. æKY LGetCell
  34038. æFc Lists.h
  34039. æT Function
  34040. æTN $A9E7
  34041. æD pascal void LGetCell(Ptr dataPtr,short *dataLen,Cell theCell,ListHandle lHandle)
  34042.     = {0x3F3C,0x0038,0xA9E7}; 
  34043. æDT LGetCell((Ptr) dataPtr,(short *) dataLen,(Cell) theCell,(ListHandle) lHandle);
  34044. æRI IV-272
  34045. æC 
  34046. Given a cell in theCell, LGetCell copies the cell’s data to the location specified by
  34047. dataPtr; dataLen is the maximum number of bytes allowed. If the data is longer than
  34048. dataLen, only dataLen bytes are copied into the location specified by dataPtr. If the
  34049. data is shorter than dataLen, dataLen is set to the true length of the cell’s data.
  34050.  
  34051. Assembly-language note:  You can invoke each of the List Manager routines
  34052.                          with a macro that has the same name as the routine
  34053.                          preceded by an underscore. These macros expand to
  34054.                          invoke to trap macro _Pack 0. The package determines
  34055.                          which routine to execute from a routine selector, an
  34056.                          integer that’s passed to it in a word on the stack.
  34057.                          The routine selectors are as follows:
  34058.  
  34059.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  34060.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  34061.                            lAddRow     .EQU    8    lClick       .EQU    24
  34062.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  34063.                            lDelColumn  .EQU    32   lNew         .EQU    68
  34064.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  34065.                            lDispose    .EQU    40   lRect        .EQU    76
  34066.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  34067.                            lDraw       .EQU    48   lSearch      .EQU    84
  34068.                            lFind       .EQU    52   lSetCell     .EQU    88
  34069.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  34070.                            lGetSelect  .EQU    60   lSize        .EQU    96
  34071.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  34072.  
  34073. æKY LFind
  34074. æFc Lists.h
  34075. æT Function
  34076. æTN $A9E7
  34077. æD pascal void LFind(short *offset,short *len,Cell theCell,ListHandle lHandle)
  34078.     = {0x3F3C,0x0034,0xA9E7}; 
  34079. æDT LFind((short *) offset,(short *) len,(Cell) theCell,(ListHandle) lHandle);
  34080. æRI IV-274
  34081. æC  
  34082. Given a cell in theCell, LFind returns the offset and the length in bytes of the
  34083. cell’s data. If an invalid cell is specified, offset and len are set to –1. A similar
  34084. procedure, LGetCell, is more convenient to use from Pascal.
  34085.  
  34086. Assembly-language note:  You can invoke each of the List Manager routines
  34087.                          with a macro that has the same name as the routine
  34088.                          preceded by an underscore. These macros expand to
  34089.                          invoke to trap macro _Pack 0. The package determines
  34090.                          which routine to execute from a routine selector, an
  34091.                          integer that’s passed to it in a word on the stack.
  34092.                          The routine selectors are as follows:
  34093.  
  34094.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  34095.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  34096.                            lAddRow     .EQU    8    lClick       .EQU    24
  34097.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  34098.                            lDelColumn  .EQU    32   lNew         .EQU    68
  34099.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  34100.                            lDispose    .EQU    40   lRect        .EQU    76
  34101.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  34102.                            lDraw       .EQU    48   lSearch      .EQU    84
  34103.                            lFind       .EQU    52   lSetCell     .EQU    88
  34104.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  34105.                            lGetSelect  .EQU    60   lSize        .EQU    96
  34106.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  34107.  
  34108. æKY LRect
  34109. æFc Lists.h
  34110. æT Function
  34111. æTN $A9E7
  34112. æD pascal void LRect(Rect *cellRect,Cell theCell,ListHandle lHandle)
  34113.     = {0x3F3C,0x004C,0xA9E7}; 
  34114. æDT LRect((Rect *) cellRect,(Cell) theCell,(ListHandle) lHandle);
  34115. æRI IV-274
  34116. æC 
  34117. LRect returns in cellRect the local (QuickDraw) coordinates of the cell specified by
  34118. theCell. If an invalid cell is specified, (0,0)(0,0) is returned in cellRect.
  34119.  
  34120. Assembly-language note:  You can invoke each of the List Manager routines
  34121.                          with a macro that has the same name as the routine
  34122.                          preceded by an underscore. These macros expand to
  34123.                          invoke to trap macro _Pack 0. The package determines
  34124.                          which routine to execute from a routine selector, an
  34125.                          integer that’s passed to it in a word on the stack.
  34126.                          The routine selectors are as follows:
  34127.  
  34128.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  34129.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  34130.                            lAddRow     .EQU    8    lClick       .EQU    24
  34131.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  34132.                            lDelColumn  .EQU    32   lNew         .EQU    68
  34133.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  34134.                            lDispose    .EQU    40   lRect        .EQU    76
  34135.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  34136.                            lDraw       .EQU    48   lSearch      .EQU    84
  34137.                            lFind       .EQU    52   lSetCell     .EQU    88
  34138.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  34139.                            lGetSelect  .EQU    60   lSize        .EQU    96
  34140.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  34141.  
  34142. æKY LSetCell
  34143. æFc Lists.h
  34144. æT Function
  34145. æTN $A9E7
  34146. æD pascal void LSetCell(Ptr dataPtr,short dataLen,Cell theCell,ListHandle lHandle)
  34147.     = {0x3F3C,0x0058,0xA9E7}; 
  34148. æDT LSetCell((Ptr) dataPtr,(short) dataLen,(Cell) theCell,(ListHandle) lHandle);
  34149. æRI IV-272
  34150. æC 
  34151. LSetCell places the data pointed to by dataPtr and of length dataLen into the specified
  34152. cell. It replaces any data that was already in the cell. If dataLen is 0, this is
  34153. equivalent to LClrCell. If theCell is not a valid cell, nothing is done. If drawing
  34154. is off, you must turn drawing on and call LDraw (or LUpdate) to display the cell’s
  34155. new value.
  34156.  
  34157. Assembly-language note:  You can invoke each of the List Manager routines
  34158.                          with a macro that has the same name as the routine
  34159.                          preceded by an underscore. These macros expand to
  34160.                          invoke to trap macro _Pack 0. The package determines
  34161.                          which routine to execute from a routine selector, an
  34162.                          integer that’s passed to it in a word on the stack.
  34163.                          The routine selectors are as follows:
  34164.  
  34165.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  34166.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  34167.                            lAddRow     .EQU    8    lClick       .EQU    24
  34168.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  34169.                            lDelColumn  .EQU    32   lNew         .EQU    68
  34170.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  34171.                            lDispose    .EQU    40   lRect        .EQU    76
  34172.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  34173.                            lDraw       .EQU    48   lSearch      .EQU    84
  34174.                            lFind       .EQU    52   lSetCell     .EQU    88
  34175.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  34176.                            lGetSelect  .EQU    60   lSize        .EQU    96
  34177.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  34178.  
  34179. æKY LSetSelect
  34180. æFc Lists.h
  34181. æT Function
  34182. æTN $A9E7
  34183. æD pascal void LSetSelect(Boolean setIt,Cell theCell,ListHandle lHandle)
  34184.     = {0x3F3C,0x005C,0xA9E7}; 
  34185. æDT LSetSelect((Boolean) setIt,(Cell) theCell,(ListHandle) lHandle);
  34186. æRI IV-273
  34187. æC 
  34188. If setIt is TRUE, LSetSelect selects the cell and redraws if it is visible and was
  34189. previously unselected. If setIt is FALSE, it deselects the cell and redraws if necessary.
  34190.  
  34191. Assembly-language note:  You can invoke each of the List Manager routines
  34192.                          with a macro that has the same name as the routine
  34193.                          preceded by an underscore. These macros expand to
  34194.                          invoke to trap macro _Pack 0. The package determines
  34195.                          which routine to execute from a routine selector, an
  34196.                          integer that’s passed to it in a word on the stack.
  34197.                          The routine selectors are as follows:
  34198.  
  34199.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  34200.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  34201.                            lAddRow     .EQU    8    lClick       .EQU    24
  34202.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  34203.                            lDelColumn  .EQU    32   lNew         .EQU    68
  34204.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  34205.                            lDispose    .EQU    40   lRect        .EQU    76
  34206.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  34207.                            lDraw       .EQU    48   lSearch      .EQU    84
  34208.                            lFind       .EQU    52   lSetCell     .EQU    88
  34209.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  34210.                            lGetSelect  .EQU    60   lSize        .EQU    96
  34211.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  34212.  
  34213. æKY LDraw
  34214. æFc Lists.h
  34215. æT Function
  34216. æTN $A9E7
  34217. æD pascal void LDraw(Cell theCell,ListHandle lHandle)
  34218.     = {0x3F3C,0x0030,0xA9E7}; 
  34219. æDT LDraw((Cell) theCell,(ListHandle) lHandle);
  34220. æRI IV-275 
  34221. æC 
  34222. Call LDraw after updating a cell’s data or selection status. (You can achieve the
  34223. same result by invalidating the cell’s rectangle and calling LUpdate in response to
  34224. the update event.) The List Manager makes its grafPort the current port, sets the
  34225. clipping region to the cell’s rectangle, and calls the list definition procedure to
  34226. draw the cell. It restores the clipping region and port before exiting.
  34227.  
  34228. Assembly-language note:  You can invoke each of the List Manager routines
  34229.                          with a macro that has the same name as the routine
  34230.                          preceded by an underscore. These macros expand to
  34231.                          invoke to trap macro _Pack 0. The package determines
  34232.                          which routine to execute from a routine selector, an
  34233.                          integer that’s passed to it in a word on the stack.
  34234.                          The routine selectors are as follows:
  34235.  
  34236.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  34237.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  34238.                            lAddRow     .EQU    8    lClick       .EQU    24
  34239.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  34240.                            lDelColumn  .EQU    32   lNew         .EQU    68
  34241.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  34242.                            lDispose    .EQU    40   lRect        .EQU    76
  34243.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  34244.                            lDraw       .EQU    48   lSearch      .EQU    84
  34245.                            lFind       .EQU    52   lSetCell     .EQU    88
  34246.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  34247.                            lGetSelect  .EQU    60   lSize        .EQU    96
  34248.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  34249.  
  34250. æKY ldraw
  34251. æFc Lists.h
  34252. æT Function
  34253. æD void ldraw(Cell *theCell,ListHandle lHandle); 
  34254. æDT ldraw((Cell *) theCell,(ListHandle) lHandle);
  34255. æRI IV-275 
  34256. æC 
  34257. Call LDraw after updating a cell’s data or selection status. (You can achieve the
  34258. same result by invalidating the cell’s rectangle and calling LUpdate in response to
  34259. the update event.) The List Manager makes its grafPort the current port, sets the
  34260. clipping region to the cell’s rectangle, and calls the list definition procedure to
  34261. draw the cell. It restores the clipping region and port before exiting.
  34262.  
  34263. Assembly-language note:  You can invoke each of the List Manager routines
  34264.                          with a macro that has the same name as the routine
  34265.                          preceded by an underscore. These macros expand to
  34266.                          invoke to trap macro _Pack 0. The package determines
  34267.                          which routine to execute from a routine selector, an
  34268.                          integer that’s passed to it in a word on the stack.
  34269.                          The routine selectors are as follows:
  34270.  
  34271.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  34272.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  34273.                            lAddRow     .EQU    8    lClick       .EQU    24
  34274.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  34275.                            lDelColumn  .EQU    32   lNew         .EQU    68
  34276.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  34277.                            lDispose    .EQU    40   lRect        .EQU    76
  34278.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  34279.                            lDraw       .EQU    48   lSearch      .EQU    84
  34280.                            lFind       .EQU    52   lSetCell     .EQU    88
  34281.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  34282.                            lGetSelect  .EQU    60   lSize        .EQU    96
  34283.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  34284.  
  34285. æKY lclick
  34286. æFc Lists.h
  34287. æT Function
  34288. æD Boolean lclick(Point *pt,short modifiers,ListHandle lHandle); 
  34289. æDT Boolean myVariable = lclick((Point *) pt,(short) modifiers,(ListHandle) lHandle);
  34290. æRI IV-273
  34291. æC 
  34292. Call LClick when there is a mouse-down event in the destination rectangle or its
  34293. scroll bars. Pt is the mouse location in local coordinates. Modifiers is the modifiers
  34294. word from the event record. LHandle is the list to be tracked. The result is TRUE if
  34295. a double-click occurred (and the two clicks took place within the same cell).
  34296.  
  34297. LClick keeps control until the mouse is released; each time through its inner loop,
  34298. it calls the routine whose pointer is in the lClikLoop field of the list record.
  34299.  
  34300. If the mouse is in the visible rectangle, cells are selected according to the state
  34301. of the modifiers and the selection flags. If the mouse was in the cells but is dragged
  34302. outside the list’s rectangle, the list is auto-scrolled. If the mouse was in a control,
  34303. the control’s definition procedure is called to track the mouse. To discover which
  34304. cell was clicked in, use the LLastClick function.
  34305.  
  34306. Assembly-language note:  You can invoke each of the List Manager routines
  34307.                          with a macro that has the same name as the routine
  34308.                          preceded by an underscore. These macros expand to
  34309.                          invoke to trap macro _Pack 0. The package determines
  34310.                          which routine to execute from a routine selector, an
  34311.                          integer that’s passed to it in a word on the stack.
  34312.                          The routine selectors are as follows:
  34313.  
  34314.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  34315.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  34316.                            lAddRow     .EQU    8    lClick       .EQU    24
  34317.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  34318.                            lDelColumn  .EQU    32   lNew         .EQU    68
  34319.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  34320.                            lDispose    .EQU    40   lRect        .EQU    76
  34321.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  34322.                            lDraw       .EQU    48   lSearch      .EQU    84
  34323.                            lFind       .EQU    52   lSetCell     .EQU    88
  34324.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  34325.                            lGetSelect  .EQU    60   lSize        .EQU    96
  34326.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  34327.  
  34328. æKY lcellsize
  34329. æFc Lists.h
  34330. æT Function
  34331. æD void lcellsize(Point *cSize,ListHandle lHandle); 
  34332. æDT lcellsize((Point *) cSize,(ListHandle) lHandle);
  34333. æRI IV-273
  34334. æC 
  34335. LCellSize sets the cellSize field in the list record to cSize and updates the visible
  34336. rectangle to contain cells of this size. This command should be used only before any
  34337. cells have been drawn.
  34338.  
  34339. Assembly-language note:  You can invoke each of the List Manager routines
  34340.                          with a macro that has the same name as the routine
  34341.                          preceded by an underscore. These macros expand to
  34342.                          invoke to trap macro _Pack 0. The package determines
  34343.                          which routine to execute from a routine selector, an
  34344.                          integer that’s passed to it in a word on the stack.
  34345.                          The routine selectors are as follows:
  34346.  
  34347.                            lActivate   .EQU    0    lAutoScroll  .EQU    16
  34348.                            lAddColumn  .EQU    4    lCellSize    .EQU    20
  34349.                            lAddRow     .EQU    8    lClick       .EQU    24
  34350.                            lAddToCell  .EQU    12   lClrCell     .EQU    28
  34351.                            lDelColumn  .EQU    32   lNew         .EQU    68
  34352.                            lDelRow     .EQU    36   lNextCell    .EQU    72
  34353.                            lDispose    .EQU    40   lRect        .EQU    76
  34354.                            lDoDraw     .EQU    44   lScroll      .EQU    80
  34355.                            lDraw       .EQU    48   lSearch      .EQU    84
  34356.                            lFind       .EQU    52   lSetCell     .EQU    88
  34357.                            lGetCell    .EQU    56   lSetSelect   .EQU    92
  34358.                            lGetSelect  .EQU    60   lSize        .EQU    96
  34359.                            lLastClick  .EQU    64   lUpdate      .EQU    100
  34360.  
  34361.  
  34362. æKY Locale.h
  34363. æC 
  34364. localeconv    setlocale    
  34365.  
  34366. The header <Locale.h> declares several macros and the setlocale 
  34367. and localeconv functions, used for program localization. The 
  34368. various locale categories are defined as macros as listed in 
  34369. Table 3-3:
  34370.  
  34371. Table 3-3    Setlocale categories
  34372. Macro name   Value   Affects
  34373.  
  34374. NULL         0
  34375. LC_ALL;      1       the program’s entire locale
  34376. LC_COLLATE;  2       behavior of the strcoll and strxfrm functions
  34377. LC_CTYPE;    3       character handling and multibyte functions
  34378. LC_MONETARY; 4       monetary formatting returned by localeconv function
  34379. LC_NUMERIC;  5       decimal-point character for formatted 
  34380.                      I/O and string conversion, and nonmonetary formatting
  34381.                      returned by localeconv function
  34382. LC_TIME;     6       the behavior of the strftime function
  34383.  
  34384. You can specify one of these categories as the first argument 
  34385. when using the setlocale function.
  34386.  
  34387.  
  34388. See also
  34389. Formatted input/output functions, multibyte functions, string 
  34390. conversion functions
  34391.  
  34392. æKY localeconv
  34393. æFc Locale.h
  34394. æC Synopsis
  34395.  
  34396. #include <Locale.h>
  34397. struct lconv {
  34398.  char *decimal_point;    
  34399.  char *thousands_sep;    
  34400.  char *grouping; 
  34401.  char *int_curr_symbol;  
  34402.  char *currency_symbol;  
  34403.  char *mon_decimal_point;    
  34404.  char *mon_thousands_sep;    
  34405.  char *mon_grouping; 
  34406.  char *positive_sign;    
  34407.  char *negative_sign;    
  34408.  char int_frac_digits;   
  34409.  char frac_digits;   
  34410.  char p_cs_precedes; 
  34411.  char p_sep_by_spaces;
  34412.  char n_cs_precedes;
  34413.  char n_sep_by_spaces;
  34414.  char p_sign_posn;
  34415.  char n_sign_posn;
  34416. }
  34417. struct lconv *localeconv (void);
  34418.  
  34419.                            Description
  34420.  
  34421. The localeconv function sets numeric formatting values for type 
  34422. struct lconv. The components of lconv can be set according to 
  34423. the rules of the current locale.
  34424. The lconv fields of type char * are strings. Any of these 
  34425. structure members (except decimal_point) can point to "", 
  34426. indicating either that the value isn’t available in the current 
  34427. locale or that its length equals zero. The lconv fields of type 
  34428. char are nonnegative numbers. Any of these structure 
  34429. members can have the value CHAR_MAX, indicating that its value 
  34430. isn’t available in the current locale. 
  34431.  
  34432. The lconv fields are listed below:  
  34433. char *decimal_point  The decimal-point character used to 
  34434.                      format nonmonetary quantities.  
  34435. char *thousands_sep  The character used to separate groups 
  34436.                      of digits to the left of the decimal-
  34437.                      point character in formatted 
  34438.                      nonmonetary quantities.  
  34439. char *grouping       A string whose elements indicate the 
  34440.                      size of each group of digits in 
  34441.                      formatted nonmonetary quantities.  
  34442. char *int_curr_symbol The international currency symbol 
  34443.                      applicable to the current locale. The 
  34444.                      first three characters contain the 
  34445.                      alphabetic international currency 
  34446.                      symbol in accordance with those 
  34447.                      specified in ISO 4217 Codes for the 
  34448.                      Representation of Currency and Funds. 
  34449.                      The fourth character (immediately 
  34450.                      preceding the null character) is the 
  34451.                      character used to separate the 
  34452.                      international currency symbol from 
  34453.                      the monetary quantity.  
  34454. char *currency_symbol For the current locale, this character 
  34455.                      denotes the local currency symbol.  
  34456. char *mon_decimal_point This character is the decimal point for 
  34457.                      formatting monetary quantities.  
  34458. char *mon_thousands_sep This character is used with formatted 
  34459.                      monetary quantities as the separator 
  34460.                      for groups of digits to the left of the 
  34461.                      decimal point.
  34462. char *mon_grouping   This string includes elements indicating the 
  34463.                      size of each group of digits in formatted 
  34464.                      monetary quantities.
  34465. char *positive_sign  This string indicates a nonnegative-
  34466.                      valued formatted monetary quantity.  
  34467. char *negative_sign  This string indicates a negative-valued 
  34468.                      formatted monetary quantity.  
  34469. char int_frac_digits For an internationally formatted 
  34470.                      monetary quantity, this element 
  34471.                      indicates the number of fractional 
  34472.                      digits (those to the right of the decimal 
  34473.                      point) to be displayed.  
  34474. char frac_digits     For a formatted monetary quantity, 
  34475.                      this element indicates the number of 
  34476.                      fractional digits (those to the right of 
  34477.                      the decimal point) to be displayed.  
  34478. char p_cs_precedes   This value is set to 1 if the 
  34479.                      currency_symbol precedes  the value, 
  34480.                      or 0 if the currency_symbol succeeds 
  34481.                      the value for a nonnegative formatted 
  34482.                      monetary quantity.  
  34483. char p_sep_by_space  This value is set to 1 if the 
  34484.                      currency_symbol is  separated by a 
  34485.                      space from the value, or  to 0 if the 
  34486.                      currency_symbol is not separated by a 
  34487.                      space from the value, for a 
  34488.                      nonnegative formatted monetary quantity.  
  34489. char n_cs_precedes   This value is set to 1 if the 
  34490.                      currency_symbol precedes  the value, 
  34491.                      or to 0 if the currency_symbol succeeds 
  34492.                      the value, for a negative formatted 
  34493.                      monetary quantity.  
  34494. char n_sep_by_space  This value is set to 1 if the 
  34495.                      currency_symbol is  separated by a 
  34496.                      space from the value, or  to 0 if the 
  34497.                      currency_symbol is not separated by a 
  34498.                      space from the value, for a negative 
  34499.                      formatted monetary quantity.  
  34500. char p_sign_posn     This character is set to a value that 
  34501.                      indicates how the positive_sign is 
  34502.                      positioned for a nonnegative formatted 
  34503.                      monetary quantity.  
  34504. char n_sign_posn     This character is set to a value that 
  34505.                      indicates how the negative_sign is 
  34506.                      positioned for a negative formatted 
  34507.                      monetary quantity.  
  34508. The following constants affect the interpretation of the grouping 
  34509. and mon_grouping fields:  
  34510.  
  34511. CHAR_MAX Performs no further grouping.  
  34512. 0        Uses the previous element repeatedly for the remainder of the digits.  
  34513. other    Examines the next element to determine the size of the next group of
  34514.          digits to the left of the current group. The value of other equals 
  34515.          the number of digits in the current group. 
  34516. The following constants affect the interpretation of the p_sign_posn and 
  34517. n_sign_posn elements:  
  34518.  
  34519. 0    The quantity and currency_symbol are surrounded by parentheses.  
  34520. 1    The sign string occurs before the quantity and currency_symbol.  
  34521. 2    The sign string occurs after the quantity and currency_symbol.  
  34522. 3    The sign string occurs immediately before the currency_symbol.  
  34523. 4    The sign string occurs immediately after the currency_symbol.  
  34524. Values within the lconv struct will only change if the user’s 
  34525. program explicitly changes them.
  34526.  
  34527.                            Return values
  34528.  
  34529. The localeconv function returns a pointer to the filled-in 
  34530. structure lconv. The lconv structure fields shouldn’t be 
  34531. modified by the program, so that the contents will remain the 
  34532. same until the next localeconv call. Subsequent calls to 
  34533. localeconv can overwrite fields within the structure. Calling 
  34534. setlocale by using one of the categories LC_ALL, LC_MONETARY, or 
  34535. LC_NUMERIC may also overwrite the contents of the lconv structure.
  34536.  
  34537. Example
  34538. The following examples show the C and US formatting for 
  34539. monetary quantities:
  34540. Element  "C" "US"
  34541.  
  34542. char *decimal_point;     "." "."
  34543. char *thousands_sep;     ""  ","
  34544. char *grouping;          ""  ""
  34545. char *int_curr_symbol;   ""  ""
  34546. char *currency_symbol;   ""  "$"
  34547. char *mon_decimal_point; ""  "."
  34548. char *mon_thousands_sep; ""  ","
  34549. char *mon_grouping;      ""  ""
  34550. char *positive_sign;     ""  "" 
  34551. char *negative_sign;     ""  ""
  34552. char int_frac_digits;    CHAR_MAX    CHAR_MAX
  34553. char frac_digits;        CHAR_MAX    CHAR_MAX
  34554. char p_cs_precedes;      CHAR_MAX    CHAR_MAX
  34555. char p_sep_by_spaces;    CHAR_MAX    CHAR_MAX
  34556. char n_cs_precedes;      CHAR_MAX    CHAR_MAX
  34557. char n_sep_by_spaces;    CHAR_MAX    CHAR_MAX
  34558. char p_sign_posn;        CHAR_MAX    CHAR_MAX
  34559. char n_sign_posn;        CHAR_MAX    CHAR_MAX
  34560.  
  34561. See also
  34562. Formatted input/output functions, multibyte functions, string 
  34563. conversion functions
  34564. \.
  34565.  
  34566. æKY setlocale
  34567. æFc Locale.h
  34568. æC Synopsis
  34569.  
  34570. #include <Locale.h>
  34571. char *setlocale (int category, const char *locale);
  34572.  
  34573.                            Description
  34574.  
  34575. The setlocale function provides control over certain categories 
  34576. of a program’s locale. You can use the setlocale function to 
  34577. change or query the program’s entire current locale or 
  34578. portions of the current locale. The category argument is one of 
  34579. the macros listed in the previous section. The LC_ALL macro 
  34580. specifies the program’s entire locale, while the other macros 
  34581. specify a portion of the locale.
  34582. The locale argument is a constant. You can specify an empty 
  34583. string constant ("") to use your system file’s setting for the 
  34584. native environment: in MPW 3.0 C, specifying the "" locale is the 
  34585. same as specifying the "US" locale. 
  34586. You can use the null string constant ("\0") for locale to find the 
  34587. name of the current native environment for a given category.
  34588. For compatibility with the draft ANSI standard, you can also 
  34589. supply a value of "C" as the locale argument. 
  34590.  
  34591.                            Return values
  34592.  
  34593. If you used a valid locale corresponding to a category, the 
  34594. setlocale function returns a pointer to the name of the locale 
  34595. for that category. If setlocale fails to locate the locale name, it 
  34596. returns a null pointer.
  34597.  
  34598. æKY localeconvæ
  34599. æDT 
  34600. struct lconv * myVariable =  localeconv (void);
  34601.  
  34602. æKY setlocaleæ
  34603. æDT 
  34604. char * myVariable = setlocale ((int) category, (const char *)locale);
  34605.  
  34606. æKY Math.h
  34607. æKL acos
  34608. asin
  34609. atan
  34610. atan2
  34611. ceil
  34612. cos
  34613. cosh
  34614. ecvt
  34615. exp
  34616. fabs
  34617. fcvt
  34618. floor
  34619. fmod
  34620. frexp
  34621. hypot
  34622. ldexp
  34623. log
  34624. log10
  34625. modf
  34626. pow
  34627. sin
  34628. sinh
  34629. sqrt
  34630. tan
  34631. tanh
  34632.  
  34633. HUGE_VAL
  34634.  
  34635. æKY acos
  34636. æFc Math.h
  34637. æT Function
  34638. æD extended acos(extended x);
  34639. æDT extended myVariable = acos((extended)x);
  34640. æC Synopsis
  34641.  
  34642. #include <Math.h>
  34643. extended acos(extended x);
  34644.  
  34645.                           Description
  34646.  
  34647. The acos function returns the arccosine of x in radians,
  34648. in the range 0 to π.
  34649.  
  34650. If x is a NaN or if the absolute value of x exceeds 1.0,
  34651. acos(x) returns a quiet NaN.  Invalid operation is signaled
  34652. if x is a signaling NaN or if |x| > 1.0.
  34653.  
  34654.                           Diagnostics
  34655.  
  34656. The acos function honors the floating-point exception flags——
  34657. invalid operation, underflow, and inexact——as prescribed by SANE.
  34658.  
  34659. See also
  34660. asin, atan, atan2
  34661. Apple Numerics Manual, 2nd edition
  34662.  
  34663.  
  34664. æKY asin
  34665. æFc Math.h
  34666. æT Function
  34667. æD extended asin(extended x);
  34668. æDT extended myVariable = asin((extended)x);
  34669. æC Synopsis
  34670.  
  34671. #include <Math.h>
  34672. extended asin(extended x);
  34673.  
  34674.                            Description
  34675.  
  34676. The asin function returns the arcsine of x in radians, in the
  34677. range -π/2 to π/2.
  34678.  
  34679. If x is a NaN or if the absolute value of x exceeds 1.0,
  34680. asin(x) returns a quiet NaN.  Invalid operation is signaled
  34681. if x is a signaling NaN or if |x| > 1.0.
  34682.  
  34683.                           Diagnostics
  34684.  
  34685. The asin function honors the floating-point exception flags——
  34686. invalid operation, underflow, and inexact——as prescribed by SANE.
  34687.  
  34688. See also
  34689. acos, atan, atan2
  34690. Apple Numerics Manual, 2nd edition
  34691.  
  34692.  
  34693. æKY atan
  34694. æFc Math.h
  34695. æT Function
  34696. æD extended atan(extended x);
  34697. æDT extended myVariable = atan((extended)x);
  34698. æC Synopsis
  34699.  
  34700. #include <Math.h>
  34701. extended atan(extended x);
  34702.  
  34703.                           Description
  34704.                           
  34705. The function atan(x) returns the arctangent of x, in the range of
  34706. -π/2 to π/2 radians.
  34707.  
  34708. If x = ±INF, then atan(x) returns ±π/2.  If x is ± 0, then atan(x)
  34709. returns x. If x is a NaN, then atan(x) returns a quiet NaN.  An
  34710. invalid operation is signaled by atan(x) only if x is a signaling
  34711. NaN.
  34712.  
  34713.                           Diagnostics
  34714.                           
  34715. The atan function honors three floating-point exception flags——
  34716. invalid operation, underflow, and inexact——as prescribed by SANE.
  34717.  
  34718. See also
  34719. acos, asin, atan2
  34720. Apple Numerics Manual, 2nd edition
  34721.  
  34722.  
  34723. æKY atan2
  34724. æFc Math.h
  34725. æT Function
  34726. æD extended atan2(extended y,extended x);
  34727. æDT extended myVariable = atan2((extended)y,(extended)x);
  34728. æC Synopsis
  34729.  
  34730. #include <Math.h>
  34731. extended atan2(extended y,extended x);
  34732.  
  34733.                            Description
  34734.  
  34735. The atan2 function returns the arctangent of y/x in radians,
  34736. in the range -π to π, using the signs of both arguments to
  34737. determine the quadrant of the return value.
  34738.  
  34739. If x is a NaN or if y is a NaN or if both x and y are infinities,
  34740. atan2(y,x) returns a quiet NaN.  If both x and y are zero, atan2
  34741. returns zero.  Invalid operation is signaled by atan2(y,x) if
  34742. both x and y are infinite or if either x or y is a signaling NaN.
  34743.  
  34744.                           Diagnostics
  34745.  
  34746. The atan2 function honors the floating-point exception flags——
  34747. invalid operation, underflow, and inexact——as prescribed by SANE.
  34748.  
  34749. See also
  34750. acos, asin, atan
  34751. Apple Numerics Manual, 2nd edition
  34752.  
  34753.  
  34754. æKY ceil
  34755. æFc Math.h
  34756. æT Function
  34757. æD extended ceil(extended x);
  34758. æDT extended myVariable = ceil((extended)x);
  34759. æC Synopsis
  34760.  
  34761. #include <Math.h>
  34762. extended ceil(extended x);
  34763.  
  34764.                           Description
  34765.  
  34766. The ceil(x) function returns the smallest integer value (in
  34767. extended floating-point format) not less than x.
  34768.  
  34769. If x is a NaN, ceil(x) returns a quiet NaN.  If x is infinite,
  34770. ceil(x) returns x.  Invalid operation is signaled by ceil(x) if
  34771. x is a signaling NaN.  If x is a non-integral finite value,
  34772. ceil(x) signals inexact.
  34773.  
  34774.                           Diagnostics
  34775.  
  34776. The ceil function honors the floating-point exception flags——
  34777. invalid operation and inexact——as prescribed by SANE.
  34778.  
  34779. See also
  34780. floor, rint
  34781. Apple Numerics Manual, 2nd edition
  34782.  
  34783.  
  34784. æKY cos
  34785. æFc Math.h
  34786. æT Function
  34787. æD extended cos(extended x);
  34788. æDT extended myVariable = cos((extended)x);
  34789. æC Synopsis
  34790.  
  34791. #include <Math.h>
  34792. extended cos(extended x);
  34793.  
  34794.                           Description                          
  34795.  
  34796. The function cos(x) computes the cosine of x, where x is expressed in
  34797. radians.
  34798.  
  34799. The cos function uses an argument reduction based on the remainder
  34800. function and pi, the nearest extended-precision approximation of π.
  34801. The cos function is periodic with respect to this pi, so its period
  34802. differs slightly from its mathematical counterpart and diverges from
  34803. its counterpart when the argument becomes very large.
  34804.  
  34805. If x is infinite or a signaling NaN, then cos(x) returns a quiet NaN
  34806. and signals invalid.
  34807.  
  34808.                           Diagnostics
  34809.                           
  34810. The cos function honors three floating-point exception flags——
  34811. invalid operation, underflow, and inexact——as prescribed by SANE.
  34812.  
  34813. See also
  34814. sin, tan
  34815. Apple Numerics Manual, 2nd edition
  34816.  
  34817.  
  34818. æKY cosh
  34819. æFc Math.h
  34820. æT Function
  34821. æD extended cosh(extended x);
  34822. æDT extended myVariable = cosh((extended)x);
  34823. æC Synopsis
  34824.  
  34825. #include <Math.h>
  34826. extended cosh(extended x);
  34827.  
  34828.                           Description
  34829.  
  34830. The function cosh(x) returns the hyberbolic cosine of x.
  34831.  
  34832. If x is a NaN, cosh(x) returns a quiet NaN.
  34833.  
  34834.                           Diagnostics
  34835.  
  34836. The cosh function honors the floating-point exception flags——
  34837. invalid operation, overflow, and inexact——as prescribed by SANE.
  34838.  
  34839. See also
  34840. exp, sinh, tanh
  34841. Apple Numerics Manual, 2nd edition
  34842.  
  34843.  
  34844. æKY ecvt
  34845. æFc Math.h
  34846. æT Function
  34847. æD char *ecvt(extended value,int ndigit,int *decpt,int *sign);
  34848. æDT char myVariable = ecvt((extended)value,(int)ndigit,(int *)decpt,(int *)sign);
  34849. æC                           Synopsis
  34850.  
  34851. #include <Math.h>
  34852. char *ecvt(extended value, int ndigit, int *decpt, int *sign);
  34853.  
  34854.                            Description
  34855.  
  34856. The ecvt function converts value to a null-terminated string of 
  34857. ndigit digits and returns a pointer to this string as the function 
  34858. result. The low-order digit is rounded.
  34859.  
  34860. The decimal point is not included in the returned string. The 
  34861. position of the decimal point is indicated by decpt, which 
  34862. indirectly stores the position of the decimal point relative to 
  34863. the returned string. If the int pointed to by decpt is negative, 
  34864. the decimal point lies to the left of the returned string. For 
  34865. example, if the string is "12345" and decpt points to an int of 3, 
  34866. the value of the string is 123.45; if decpt points to –3, the value 
  34867. of the string is .00012345.
  34868.  
  34869. If the sign of the converted value is negative, the int pointed to 
  34870. by sign is nonzero; otherwise it is zero.
  34871.  
  34872. In ecvt, ndigit specifies the number of digits in the string.
  34873.  
  34874.                            Note
  34875.  
  34876. The string pointed to by the function result is static 
  34877. data whose contents are overwritten by each call. To 
  34878. preserve the value, copy it before calling the function again.
  34879.  
  34880. See also
  34881. fcvt, printf
  34882. Apple Numerics Manual, 2nd edition
  34883.  
  34884.  
  34885. æKY exp
  34886. æFc Math.h
  34887. æT Function
  34888. æD extended exp(extended x);
  34889. æDT extended myVariable = exp((extended)x);
  34890. æC Synopsis
  34891.  
  34892. #include <Math.h>
  34893. extended exp(extended x); 
  34894.  
  34895.                           Description
  34896.  
  34897. The function exp(x) returns the base-e or natural exponential e^x.
  34898.  
  34899. Special cases for exp:
  34900.  
  34901. If x = +INF, then exp(x) returns +INF and does not signal an exception. 
  34902. If x = –INF, then exp(x) returns 0 and does not signal an exception.
  34903. If x is a NaN, then exp(x) returns a quiet NaN.
  34904.  
  34905.                           Diagnostics
  34906.                           
  34907. The function exp(x) honors the four floating-point exception flags——
  34908. invalid operation, underflow, overflow, and inexact——as prescribed
  34909. by SANE.
  34910.  
  34911. See also
  34912. exp1, exp2
  34913. Apple Numerics Manual, 2nd edition
  34914.  
  34915.  
  34916. æKY fabs
  34917. æFc Math.h
  34918. æT Function
  34919. æD extended fabs(extended x);
  34920. æDT extended myVariable = fabs((extended)x);
  34921. æC Synopsis
  34922.  
  34923. #include <Math.h>
  34924. extended fabs(extended x);
  34925.  
  34926.                            Description
  34927.  
  34928. The fabs(x) function returns |x|, the absolute value of x.
  34929.  
  34930. In non-mc68881 mode, the absolute value is evaluated via
  34931. manipulation of the sign bit of x, and no exceptions are raised.
  34932.  
  34933. In mc68881 mode, signaling NaN input will raise the invalid
  34934. operation and CURSIGNAN exceptions.  In this case, fabs returns
  34935. a quiet NaN with its sign bit cleared.
  34936.  
  34937.                            Diagnostics
  34938.                            
  34939. In mc68881 mode, fabs honors the invalid operation exception as
  34940. prescribed by SANE.
  34941.  
  34942. See also
  34943. Apple Numerics Manual, 2nd edition
  34944.  
  34945.  
  34946. æKY fcvt
  34947. æFc Math.h
  34948. æT Function
  34949. æD char *fcvt(extended value,int ndigit,int *decpt,int *sign);
  34950. æDT char myVariable = fcvt((extended)value,(int)ndigit,(int *)decpt,(int *)sign);
  34951. æC Synopsis
  34952.  
  34953. #include <Math.h>
  34954. char *fcvt(extended value, int ndigit, int *decpt, int *sign);
  34955.  
  34956.                            Description
  34957.  
  34958. The fcvt function provides fixed-point output in the style of 
  34959. Fortran F-format output.  It converts value to a null-terminated
  34960. string representing a floating-point number with ndigit digits
  34961. to the right of the decimal point and returns a pointer to this
  34962. string.  The low-order digit is rounded.
  34963.  
  34964. The decimal point is not included in the returned string.  The
  34965. position of the decimal point is indicated by decpt, which
  34966. indirectly stores the position of the decimal point relative
  34967. to the returned string.  If the int pointed to by decpt is 
  34968. negative, the decimal point lies to the left of the returned
  34969. string.  For example, if the string is "12345" and decpt points
  34970. to an int of 3, the value of the string is 123.45; if decpt
  34971. points to -3, the value of the string is .00012345.
  34972.  
  34973. If the sign of the converted value is negative, the int pointed
  34974. to by sign is nonzero; otherwise it is zero.
  34975.  
  34976. The function fcvt differs from ecvt in its interpretation of ndigit:
  34977.  
  34978.     In fcvt, ndigit specifies the number of digits to the right of 
  34979.     the decimal point.
  34980.     
  34981.     In ecvt, ndigit specifies the number of digits in the string.
  34982.  
  34983.  
  34984.                            Note
  34985.  
  34986. The string pointed to by the function result is static data whose
  34987. contents are overwritten by each call. To preserve the value,
  34988. copy it before calling the function again.
  34989.  
  34990. See also
  34991. ecvt, printf
  34992. Apple Numerics Manual, 2nd edition
  34993.  
  34994.  
  34995. æKY floor
  34996. æFc Math.h
  34997. æT Function
  34998. æD extended floor(extended x);
  34999. æDT extended myVariable = floor((extended)x);
  35000. æC Synopsis
  35001.  
  35002. #include <Math.h>
  35003. extended floor(extended x);
  35004.  
  35005.                           Description
  35006.  
  35007. The floor(x) function returns the largest integer value (in
  35008. extended floating-point format) not greater than x.
  35009.  
  35010. If x is a NaN, floor(x) returns a quiet NaN.  If x is infinite,
  35011. floor(x) returns x.  Invalid operation is signaled by floor(x)
  35012. if x is a signaling NaN.  If x is a non-integral finite value,
  35013. floor(x) signals inexact.
  35014.  
  35015.                           Diagnostics
  35016.  
  35017. The floor function honors the floating-point exception flags——
  35018. invalid operation and inexact——as prescribed by SANE.
  35019.  
  35020. See also
  35021. ceil, rint
  35022. Apple Numerics Manual, 2nd edition
  35023.  
  35024.  
  35025. æKY fmod
  35026. æFc Math.h
  35027. æT Function
  35028. æD extended fmod(extended x,extended y);
  35029. æDT extended myVariable = fmod((extended)x,(extended)y);
  35030. æC  Synopsis
  35031.  
  35032. #include <Math.h>
  35033. extended fmod(extended x, extended y);
  35034.  
  35035.                            Description
  35036.  
  35037. Whenever possible, the fmod(x, y) function returns the number
  35038. f with the same sign as x, such that x = i*y + f for some 
  35039. integer i, and |f| < |y|. If y is 0, fmod returns a quiet NaN.
  35040.  
  35041.                            Diagnostics
  35042.  
  35043. The function fmod honors the floating-point exception flag
  35044. invalid operation as prescribed by SANE.
  35045.  
  35046. See also
  35047. modf, remainder
  35048. Apple Numerics Manual, 2nd edition
  35049.  
  35050.  
  35051. æKY frexp
  35052. æFc Math.h
  35053. æT Function
  35054. æD extended frexp(extended x,int *exp);
  35055. æDT extended myVariable = frexp((extended)x,(int *)exp);
  35056. æC Synopsis
  35057.  
  35058. #include <Math.h>
  35059. extended frexp(extended value, int *exp);
  35060.  
  35061.                            Description
  35062.  
  35063. The function frexp(value,exp) returns the mantissa of its
  35064. extended operand value and stores the integer exponent in
  35065. variable *exp. Every nonzero number can be written uniquely
  35066. as x * 2^n, where the mantissa (fraction) x is in the range
  35067. 0.5 ≤ |x| < 1.0 and the exponent n is an integer. Note that
  35068. the mantissa here differs from the significand described in
  35069. the Apple Numerics Manual, 2nd edition, whose normal values
  35070. are in the range 1.0 ≤ |x| < 2.0.
  35071.  
  35072. For special cases, this function returns a quiet NaN or signed 
  35073. infinity as appropriate (NaN or infinite operands, respectively).
  35074.  
  35075.                           Diagnostics
  35076.  
  35077. The frexp function honors the floating-point exception flag
  35078. invalid operation as prescribed by SANE.
  35079.  
  35080. See also
  35081. ldexp, logb
  35082. Apple Numerics Manual, 2nd edition
  35083.  
  35084.  
  35085. æKY hypot
  35086. æFc Math.h
  35087. æT Function
  35088. æD extended hypot(extended x,extended y);
  35089. æDT extended myVariable = hypot((extended)x,(extended)y);
  35090. æC                           Synopsis
  35091.  
  35092. #include <Math.h>
  35093. extended hypot(extended x, extended y);
  35094.  
  35095.                            Description
  35096.  
  35097. The hypot function returns the square root of the sum of 
  35098. two squared numbers:  sqrt(x*x + y*y).
  35099.  
  35100. The hypot function includes error handling for those cases 
  35101. when the correct value would overflow. If the function result 
  35102. overflows, hypot returns HUGE_VAL with the correct sign, and 
  35103. raises the overflow exception flag.
  35104.  
  35105.                           Diagnostics
  35106.  
  35107. The function hypot honors the floating-point exception flags——
  35108. invalid operation, underflow, overflow, and inexact——as prescribed 
  35109. by SANE.
  35110.  
  35111. See also
  35112. Apple Numerics Manual, 2nd edition
  35113.  
  35114. æKY ldexp
  35115. æFc Math.h
  35116. æT Function
  35117. æD extended ldexp(extended x,int n);
  35118. æDT extended myVariable = ldexp((extended)x,(int)n);
  35119. æC Synopsis
  35120.  
  35121. #include <Math.h>
  35122. extended ldexp(extended x, int exp);
  35123.  
  35124.                            Description
  35125.  
  35126. The ldexp function returns the quantity x * 2^exp.
  35127.  
  35128.                           Diagnostics
  35129.  
  35130. The ldexp function honors the floating-point exception flags——
  35131. invalid operation, underflow, overflow, and inexact——as
  35132. prescribed by SANE.
  35133.  
  35134. See also
  35135. frexp, scalb
  35136. Apple Numerics Manual, 2nd edition
  35137.  
  35138.  
  35139. æKY log
  35140. æFc Math.h
  35141. æT Function
  35142. æD extended log(extended x);
  35143. æDT extended myVariable = log((extended)x);
  35144. æC Synopsis
  35145.  
  35146. #include <Math.h>
  35147. extended log(extended x);
  35148.  
  35149.                           Description
  35150.  
  35151. The function log(x) returns the base e or natural logarithm
  35152. of its argument x.
  35153.  
  35154. Special cases for log:
  35155.  
  35156. If x is +INF, then log(x) returns +INF and signals no exceptions.
  35157. If x is 0, then log(x) returns -INF and signals divide-by-zero.  
  35158. If x < 0, then log(x) returns a quiet NaN and signals invalid.
  35159.  
  35160.                           Diagnostics
  35161.  
  35162. The log function honors three floating-point exception flags——
  35163. invalid operation, divide-by-zero, and inexact——as prescribed
  35164. by SANE.
  35165.  
  35166. See also
  35167. log1, log2, logb
  35168. Apple Numerics Manual, 2nd edition
  35169.  
  35170.  
  35171. æKY log10
  35172. æFc Math.h
  35173. æT Function
  35174. æD extended log10(extended x);
  35175. æDT extended myVariable = log10((extended)x);
  35176. æC Synopsis
  35177.  
  35178. #include <Math.h>
  35179. extended log10(extended x);
  35180.  
  35181.                            Description
  35182.  
  35183. The log10(x) function returns the base 10 logarithm of x.
  35184.  
  35185. If x is a NaN or is negative, log10(x) returns a quiet NaN.  If
  35186. x is +∞, log10(x) returns +∞.  If x is zero, log10(x)
  35187. returns -∞ and signals divide by zero.
  35188.  
  35189.                           Diagnostics
  35190.  
  35191. The log10 function honors the floating-point exception flags——
  35192. invalid operation, divide by zero, and inexact——as prescribed
  35193. by SANE.
  35194.  
  35195. See also
  35196. log, log1, log2
  35197. Apple Numerics Manual, 2nd edition
  35198.  
  35199.  
  35200. æKY modf
  35201. æFc Math.h
  35202. æT Function
  35203. æD extended modf(extended x,extended *ip);
  35204. æDT extended myVariable = modf((extended)x,(extended *)ip);
  35205. æC                Synopsis
  35206.  
  35207. #include <Math.h>
  35208. extended modf(extended value, extended *ip);
  35209.  
  35210.                           Description
  35211.  
  35212. The function modf(x,ip) returns the fractional part of x and
  35213. stores the integral part indirectly in the location pointed
  35214. to by ip.  Both the return value and the value stored in *ip
  35215. share the same sign as x.
  35216.  
  35217. If x is infinite, modf(x,ip) returns a zero with the sign of x
  35218. and sets *ip to x.  If x is a NaN, modf(x,ip) returns a quiet
  35219. NaN and sets *ip to the same quiet NaN.
  35220.  
  35221.                           Diagnostics
  35222.  
  35223. This function honors one floating-point exception flag, invalid
  35224. operation, prescribed by SANE.  This flag is raised when the
  35225. input argument x is a signaling NaN.
  35226.  
  35227. See also
  35228. fmod, remainder
  35229. Apple Numerics Manual, 2nd edition
  35230.  
  35231.  
  35232. æKY pow
  35233. æFc Math.h
  35234. æT Function
  35235. æD extended pow(extended x, extended y);
  35236. æDT extended myVariable = pow((extended)x,(extended)y);
  35237. æC                Synopsis
  35238.  
  35239. #include <Math.h>
  35240. extended pow(extended x, extended y);
  35241.  
  35242.                            Description
  35243.  
  35244. The function pow(x,y) is equivalent to the SANE function
  35245. power(x,y), which returns x^y.
  35246.  
  35247. For special cases, pow returns a quiet NaN or signed infinity as
  35248. appropriate.
  35249.  
  35250.                           Diagnostics
  35251.  
  35252. This function honors the floating-point exception flags——
  35253. invalid operation, underflow, overflow, divide by zero, and
  35254. inexact——as prescribed by SANE.
  35255.  
  35256. See also
  35257. power
  35258. Apple Numerics Manual, 2nd edition
  35259.  
  35260.  
  35261. æKY sin
  35262. æFc Math.h
  35263. æT Function
  35264. æD extended sin(extended x);
  35265. æDT extended myVariable = sin((extended)x);
  35266. æC Synopsis
  35267.  
  35268. #include <Math.h>
  35269. extended sin(extended x);
  35270.  
  35271.                           Description                          
  35272.  
  35273. The function sin(x) computes the sine of x, where x is expressed in
  35274. radians.
  35275.  
  35276. The sin function uses an argument reduction based on the remainder
  35277. function and pi, the nearest extended-precision approximation of π.
  35278. The sin function is periodic with respect to this pi, so its period
  35279. differs slightly from its mathematical counterpart and diverges from
  35280. its counterpart when the argument becomes very large.
  35281.  
  35282. If x is infinite or a signaling NaN, then sin(x) returns a quiet NaN
  35283. and signals invalid.
  35284.  
  35285.                           Diagnostics
  35286.                           
  35287. The sin function honors three floating-point exception flags——
  35288. invalid operation, underflow, and inexact——as prescribed by SANE.
  35289.  
  35290. See also
  35291. cos, tan
  35292. Apple Numerics Manual, 2nd edition
  35293.  
  35294.  
  35295. æKY sinh
  35296. æFc Math.h
  35297. æT Function
  35298. æD extended sinh(extended x);
  35299. æDT extended myVariable = sinh((extended)x);
  35300. æC Synopsis
  35301.  
  35302. #include <Math.h>
  35303. extended sinh(extended x);
  35304.  
  35305.                           Description
  35306.  
  35307. The function sinh(x) returns the hyberbolic sine of x.
  35308.  
  35309. If x is a NaN, sinh(x) returns a quiet NaN.
  35310.  
  35311.                           Diagnostics
  35312.  
  35313. The sinh function honors the floating-point exception flags——
  35314. invalid operation, underflow, overflow, and inexact——as
  35315. prescribed by SANE.
  35316.  
  35317. See also
  35318. exp, cosh, tanh
  35319. Apple Numerics Manual, 2nd edition
  35320.  
  35321.  
  35322. æKY sqrt
  35323. æFc Math.h
  35324. æT Function
  35325. æD extended sqrt(extended x);
  35326. æDT extended myVariable = sqrt((extended)x);
  35327. æC Synopsis
  35328.  
  35329. #include <Math.h>
  35330. extended sqrt(extended x);
  35331.  
  35332.                           Description                          
  35333.  
  35334. The function sqrt(x) computes the square root of x.
  35335.  
  35336. Special cases for sqrt:
  35337.  
  35338. If x is a quiet NaN, sqrt(x) returns a quiet NaN and signals no
  35339.   exceptions.
  35340. If x is a signaling NaN or if x < 0, sqrt(x) returns a quiet NaN
  35341.   and signals invalid operation.
  35342.  
  35343.                           Diagnostics
  35344.                           
  35345. The sqrt function honors two floating-point exception flags——
  35346. invalid operation and inexact——as prescribed by SANE.
  35347.  
  35348. See also
  35349. Apple Numerics Manual, 2nd edition
  35350.  
  35351.  
  35352. æKY tan
  35353. æFc Math.h
  35354. æT Function
  35355. æD extended tan(extended x);
  35356. æDT extended myVariable = tan((extended)x);
  35357. æC Synopsis
  35358.  
  35359. #include <Math.h>
  35360. extended tan(extended x);
  35361.  
  35362.                           Description                          
  35363.  
  35364. The function tan(x) computes the tangent of x, where x is
  35365. expressed in radians.
  35366.  
  35367. The tan function uses an argument reduction based on the
  35368. remainder function and pi, the nearest extended-precision
  35369. approximation of π.  The tan function is periodic with respect
  35370. to this pi, so its period differs slightly from its mathematical
  35371. counterpart and diverges from its counterpart when the argument
  35372. becomes very large.
  35373.  
  35374.  
  35375. Special cases for tan:
  35376.  
  35377. If x is infinite or a signaling NaN, then tan(x) returns a quiet
  35378.   NaN and signals invalid.
  35379. If x is zero, then tan(x) returns x [including sign of x].
  35380. If x is ±pi/2, then tan(x) returns ±INF and signals divide-by-zero
  35381.   and inexact.
  35382.  
  35383.                           Diagnostics
  35384.                           
  35385. The tan function honors four floating-point exception flags——
  35386. invalid operation, underflow, divide-by-zero, and inexact——as
  35387. prescribed by SANE.
  35388.  
  35389. See also
  35390. sin, cos, atan
  35391. Apple Numerics Manual, 2nd edition
  35392.  
  35393.  
  35394. æKY tanh
  35395. æFc Math.h
  35396. æT Function
  35397. æD extended tanh(extended x);
  35398. æDT extended myVariable = tanh((extended)x);
  35399. æC Synopsis
  35400.  
  35401. #include <Math.h>
  35402. extended tanh(extended x);
  35403.  
  35404.                           Description
  35405.  
  35406. The function tanh(x) returns the hyberbolic tangent of x.
  35407.  
  35408. If x is a NaN, tanh(x) returns a quiet NaN.
  35409.  
  35410.                           Diagnostics
  35411.  
  35412. The tanh function honors the floating-point exception flags——
  35413. invalid operation, underflow, and inexact——as prescribed by SANE.
  35414.  
  35415. See also
  35416. exp, cosh, sinh
  35417. Apple Numerics Manual, 2nd edition
  35418.  
  35419.  
  35420. æKY HUGE_VAL
  35421. æFc Math.h
  35422. æT Macro
  35423. æD #define HUGE_VAL inf();
  35424. æDT extended myVariable = HUGE_VAL;
  35425. æC Synopsis
  35426.  
  35427. #include <Math.h>
  35428. #define HUGE_VAL inf();
  35429.  
  35430.                           Description
  35431.  
  35432. HUGE_VAL is a positive extended value.  An extended function
  35433. which overflows returns HUGE_VAL with the proper sign.  Thus,
  35434. HUGE_VAL equals positive infinity.
  35435.  
  35436. See also
  35437. inf
  35438. Apple Numerics Manual, 2nd edition
  35439.  
  35440.  
  35441. æKY Memory.h
  35442. æKL ApplicZone
  35443. BlockMove
  35444. CompactMem
  35445. DisposHandle
  35446. DisposPtr
  35447. EmptyHandle
  35448. FreeMem
  35449. GetApplLimit
  35450. GetHandleSize
  35451. GetPtrSize
  35452. GetZone
  35453. GZSaveHnd
  35454. HandleZone
  35455. HClrRBit
  35456. HGetState
  35457. HLock
  35458. HNoPurge
  35459. HPurge
  35460. HSetRBit
  35461. HSetState
  35462. HUnlock
  35463. InitApplZone
  35464. InitZone
  35465. MaxApplZone
  35466. MaxBlock
  35467. MaxMem
  35468. MemError
  35469. MFFreeMem
  35470. MFMaxMem
  35471. MFTempDisposHandle
  35472. MFTempHLock
  35473. MFTempHUnlock
  35474. MFTempNewHandle
  35475. MFTopMem
  35476. MoreMasters
  35477. MoveHHi
  35478. NewEmptyHandle
  35479. NewHandle
  35480. NewHandleClear
  35481. NewHandleSys
  35482. NewHandleSysClear
  35483. NewPtr
  35484. NewPtrClear
  35485. NewPtrSys
  35486. NewPtrSysClear
  35487. PtrZone
  35488. PurgeMem
  35489. PurgeSpace
  35490. ReallocHandle
  35491. RecoverHandle
  35492. ResrvMem
  35493. SetApplBase
  35494. SetApplLimit
  35495. SetGrowZone
  35496. SetHandleSize
  35497. SetPtrSize
  35498. SetZone
  35499. StackSpace
  35500. StripAddress
  35501. SystemZone
  35502. TopMem
  35503.  
  35504. GrowZoneProcPtr
  35505. maxSize
  35506. Size
  35507. THz
  35508. Zone
  35509.  
  35510. æKY maxSize
  35511. æFc Memory.h
  35512. æT #define
  35513. æD #define maxSize 0x800000 /*Max data block size is 8 megabytes*/
  35514. æC #define maxSize  0x800000 /*Max data block size is 8 megabytes*/
  35515.  
  35516. æKY Size
  35517. æFc Memory.h
  35518. æT typedef
  35519. æD typedef long Size;
  35520. æC For specifying the sizes of blocks in the heap, the Memory Manager defines a special
  35521. type called Size:
  35522.  
  35523.   TYPE Size = LONGINT;
  35524.  
  35525. All Memory Manager routines that deal with block sizes expect parameters of type Size
  35526. or return them as results.
  35527.  
  35528. æKY GrowZoneProcPtr
  35529. æFc Memory.h
  35530. æT typedef
  35531. æD typedef pascal long (*GrowZoneProcPtr)(Size cbNeeded);
  35532. æC 
  35533.  
  35534. æKY Zone
  35535. THz
  35536. æFc Memory.h
  35537. æT struct
  35538. æD struct Zone {
  35539.     Ptr bkLim;
  35540.     Ptr purgePtr;
  35541.     Ptr hFstFree;
  35542.     long zcbFree;
  35543.     GrowZoneProcPtr gzProc;
  35544.     short moreMast;
  35545.     short flags;
  35546.     short cntRel;
  35547.     short maxRel;
  35548.     short cntNRel;
  35549.     short maxNRel;
  35550.     short cntEmpty;
  35551.     short cntHandles;
  35552.     long minCBFree;
  35553.     ProcPtr purgeProc;
  35554.     Ptr sparePtr;
  35555.     Ptr allocPtr;
  35556.     short heapData;
  35557. };
  35558.  
  35559. typedef struct Zone Zone;
  35560. typedef Zone *THz;
  35561.  
  35562. æC 
  35563. »Structure of Heap Zones
  35564.  
  35565. Each heap zone begins with a 52-byte zone header and ends with a 12-byte zone trailer
  35566. (see Figure 11). The header contains all the information the Memory Manager needs
  35567. about that heap zone; the trailer is just a minimum-size free block (described in the
  35568. next section) placed at the end of the zone as a marker. All the remaining space
  35569. between the header and trailer is available for allocation.
  35570.  
  35571. In Pascal, a heap zone is defined as a zone record of type Zone. It’s always referred
  35572. to with a zone pointer of type THz (“the heap zone”):
  35573.  
  35574. TYPE  THz  = ^Zone;
  35575.       Zone = RECORD
  35576.                bkLim:       Ptr;      {zone trailer block}
  35577.                purgePtr:    Ptr;      {used internally}
  35578.                hFstFree:    Ptr;      {first free master pointer}
  35579.                zcbFree:     LONGINT;  {number of free bytes}
  35580.                gzProc:      ProcPtr;  {grow zone function}
  35581.                moreMast:    INTEGER;  {master pointers to allocate}
  35582.                flags:       INTEGER;  {used internally}
  35583.                cntRel:      INTEGER;  {not used}
  35584.                maxRel:      INTEGER;  {not used}
  35585.                cntNRel:     INTEGER;  {not used}
  35586.                maxNRel:     INTEGER;  {not used}
  35587.                cntEmpty:    INTEGER;  {not used}
  35588.                cntHandles:  INTEGER;  {not used}
  35589.                minCBFree:   LONGINT;  {not used}
  35590.                purgeProc:   ProcPtr;  {purge warning procedure}
  35591.                sparePtr:    Ptr;      {used internally}
  35592.                allocPtr:    Ptr;      {used internally}
  35593.                heapData:    INTEGER   {first usable byte in zone}
  35594.              END;
  35595.  
  35596. Warning:  The fields of the zone header are for the Memory Manager’s own
  35597.           internal use. You can examine the contents of the zone’s fields,
  35598.           but in general it doesn’t make sense for your program to try to
  35599.           change them. The few exceptions are noted below in the discussions
  35600.           of the specific fields.
  35601.  
  35602. BkLim is a pointer to the zone’s trailer block. Since the trailer is the last block
  35603. in the zone, bkLim is a pointer to the byte following the last byte of usable space
  35604. in the zone.
  35605.  
  35606. HFstFree is a pointer to the first free master pointer in the zone. Instead of just
  35607. allocating space for one master pointer each time a relocatable block is created, the
  35608. Memory Manager “preallocates” several master pointers at a time; as a group they form
  35609. a nonrelocatable block. The moreMast field of the zone record tells the Memory Manager
  35610. how many master pointers at a time to preallocate for this zone.
  35611.  
  35612. Note:  Master pointers are allocated 32 at a time for the system heap zone
  35613.        and 64 at a time for the application zone; this may be different on
  35614.        future versions of the Macintosh.
  35615.  
  35616. All master pointers that are allocated but not currently in use are linked together
  35617. into a list beginning in the hFstFree field. When you allocate a new relocatable
  35618. block, the Memory Manager removes the first available master pointer from this list,
  35619. sets it to point to the new block, and returns its address to you as a handle to the
  35620. block. (If the list is empty, it allocates a fresh block of moreMast master pointers.)
  35621. When you release a relocatable block, its master pointer isn’t released, but is
  35622. linked onto the beginning of the list to be reused. Thus the amount of space devoted
  35623. to master pointers can increase, but can never decrease until the zone is reinitialized.
  35624.  
  35625. The zcbFree field always contains the number of free bytes remaining in the zone. As
  35626. blocks are allocated and released, the Memory Manager adjusts zcbFree accordingly.
  35627. This number represents an upper limit on the size of block you can allocate from this
  35628. heap zone.
  35629.  
  35630. Warning:  It may not actually be possible to allocate a block as big as
  35631.           zcbFree bytes. Because nonrelocatable and locked blocks can’t be
  35632.           moved, it isn’t always possible to collect all the free space into
  35633.           a single block by compaction.
  35634.  
  35635. The gzProc field is a pointer to the grow zone function. You can supply a pointer to
  35636. your own grow zone function when you create a new heap zone and can change it at any
  35637. time.
  35638.  
  35639. Warning:  Don’t store directly into the gzProc field; if you want to supply
  35640.           your own grow zone function, you must do so with a procedure call
  35641.           (InitZone or SetGrowZone).
  35642.  
  35643. PurgeProc is a pointer to the zone’s purge warning procedure, or NIL if there is
  35644. none. The Memory Manager will call this procedure before it purges a block from the
  35645. zone.
  35646.  
  35647. Warning:  Whenever you call the Resource Manager with SetResPurge(TRUE),
  35648.           it installs its own purge warning procedure, overriding any purge
  35649.           warning procedure you’ve specified to the Memory Manager; for further
  35650.           details, see the Resource Manager chapter.
  35651.  
  35652. The last field of a zone record, heapData, is a dummy field marking the bottom of the
  35653. zone’s usable memory space.
  35654.  
  35655. HeapData nominally contains an integer, but this integer has no significance in
  35656. itself—it’s just the first two bytes in the block header of the first block in the
  35657. zone. The purpose of the heapData field is to give you a way of locating the effective
  35658. bottom of the zone. For example, if myZone is a zone pointer, then
  35659.  
  35660.   @(myZone^.heapData)
  35661.  
  35662. is a pointer to the first usable byte in the zone, just as
  35663.  
  35664.   myZone^.bkLim
  35665.  
  35666. is a pointer to the byte following the last usable byte in the zone.
  35667.  
  35668. æKY GetApplLimit
  35669. æFc Memory.h
  35670. æT Function
  35671. æD pascal Ptr GetApplLimit(void)
  35672.     = {0x2EB8,0x0130}; 
  35673. æDT Ptr myVariable = GetApplLimit()(void);
  35674. æRI II-29
  35675. æC 
  35676. GetApplLimit returns the current application heap limit. It can be used in conjunction
  35677. with SetApplLimit, described below, to determine and then change the application heap
  35678. limit.
  35679.  
  35680. Assembly-language note:  The global variable ApplLimit contains the
  35681.                          current application heap limit.
  35682.  
  35683. æKY GetZone
  35684. æFc Memory.h
  35685. æT Function
  35686. æD pascal THz GetZone(void); 
  35687. æDT THz myVariable = GetZone()(void);
  35688. æRI II-31
  35689. æC 
  35690. Trap macro  _GetZone
  35691. On exit     A0:  function result (pointer)
  35692.             D0:  result code (word)
  35693.  
  35694. GetZone returns a pointer to the current heap zone.
  35695.  
  35696. Assembly-language note:  The global variable TheZone contains a
  35697.                          pointer to the current heap zone.
  35698.  
  35699. Result codes    noErr    No error
  35700.  
  35701. æKY SystemZone
  35702. æFc Memory.h
  35703. æT Function
  35704. æD pascal THz SystemZone(void)
  35705.     = {0x2EB8,0x02A6}; 
  35706. æDT THz myVariable = SystemZone()(void);
  35707. æRI II-32
  35708. æC 
  35709. [Not in ROM]
  35710.  
  35711. SystemZone returns a pointer to the system heap zone.
  35712.  
  35713. Assembly-language note:  The global variable SysZone contains
  35714.                          a pointer to the system heap zone.
  35715.  
  35716. æKY ApplicZone
  35717. æFc Memory.h
  35718. æT Function
  35719. æD pascal THz ApplicZone(void)
  35720.     = {0x2EB8,0x02AA}; 
  35721. æDT THz myVariable = ApplicZone()(void);
  35722. æRI II-32, N83-1
  35723. æC  
  35724. [Not in ROM]
  35725.  
  35726. ApplicZone returns a pointer to the original application heap zone.
  35727.  
  35728. Assembly-language note:  The global variable ApplZone contains
  35729.                          a pointer to the original application heap zone.
  35730.  
  35731. æKY NewHandle
  35732. æFc Memory.h
  35733. æT Function
  35734. æD pascal Handle NewHandle(Size byteCount); 
  35735. æDT Handle myVariable = NewHandle((Size) byteCount);
  35736. æMM
  35737. æRT 7, 117, 205
  35738. æRI I-76, 80, II-32, N7-2, N117-17, P-51, 177
  35739. æC 
  35740. Trap macro  _NewHandle
  35741.             _NewHandle ,SYS        (applies to system heap)
  35742.             _NewHandle ,CLEAR      (clears allocated block)
  35743.             _NewHandle ,SYS,CLEAR  (applies to system heap and clears
  35744.                                     allocated block)
  35745. On entry    D0:  logicalSize (long word)
  35746. On exit     A0:  function result (handle)
  35747.             D0:  result code (word)
  35748.  
  35749. NewHandle attempts to allocate a new relocatable block of logicalSize bytes from the
  35750. current heap zone and then return a handle to it. The new block will be unlocked and
  35751. unpurgeable. If logicalSize bytes can’t be allocated, NewHandle returns NIL.
  35752.  
  35753. NewHandle will pursue all available avenues to create a free block of the requested
  35754. size, including compacting the heap zone, increasing its size, purging blocks from
  35755. it, and calling its grow zone function, if any.
  35756.  
  35757. Result codes    noErr         No error
  35758.                 memFullErr    Not enough room in heap zone
  35759.  
  35760. æKY NewHandleSys
  35761. æFc Memory.h
  35762. æT Function
  35763. æD pascal Handle NewHandleSys(Size byteCount); 
  35764. æDT Handle myVariable = NewHandleSys((Size) byteCount);
  35765. æRT 219
  35766. æC 
  35767. Trap macro  _NewHandle
  35768.             _NewHandle ,SYS        (applies to system heap)
  35769.             _NewHandle ,CLEAR      (clears allocated block)
  35770.             _NewHandle ,SYS,CLEAR  (applies to system heap and clears
  35771.                                     allocated block)
  35772. On entry    D0:  logicalSize (long word)
  35773. On exit     A0:  function result (handle)
  35774.             D0:  result code (word)
  35775.  
  35776. NewHandle attempts to allocate a new relocatable block of logicalSize bytes from the
  35777. current heap zone and then return a handle to it. The new block will be unlocked and
  35778. unpurgeable. If logicalSize bytes can’t be allocated, NewHandle returns NIL.
  35779.  
  35780. NewHandle will pursue all available avenues to create a free block of the requested
  35781. size, including compacting the heap zone, increasing its size, purging blocks from
  35782. it, and calling its grow zone function, if any.
  35783.  
  35784. Result codes    noErr         No error
  35785.                 memFullErr    Not enough room in heap zone
  35786.  
  35787. æKY NewHandleClear
  35788. æFc Memory.h
  35789. æT Function
  35790. æD pascal Handle NewHandleClear(Size byteCount); 
  35791. æDT Handle myVariable = NewHandleClear((Size) byteCount);
  35792. æRT 219
  35793. æC 
  35794. Trap macro  _NewHandle
  35795.             _NewHandle ,SYS        (applies to system heap)
  35796.             _NewHandle ,CLEAR      (clears allocated block)
  35797.             _NewHandle ,SYS,CLEAR  (applies to system heap and clears
  35798.                                     allocated block)
  35799. On entry    D0:  logicalSize (long word)
  35800. On exit     A0:  function result (handle)
  35801.             D0:  result code (word)
  35802.  
  35803. NewHandle attempts to allocate a new relocatable block of logicalSize bytes from the
  35804. current heap zone and then return a handle to it. The new block will be unlocked and
  35805. unpurgeable. If logicalSize bytes can’t be allocated, NewHandle returns NIL.
  35806.  
  35807. NewHandle will pursue all available avenues to create a free block of the requested
  35808. size, including compacting the heap zone, increasing its size, purging blocks from
  35809. it, and calling its grow zone function, if any.
  35810.  
  35811. Result codes    noErr         No error
  35812.                 memFullErr    Not enough room in heap zone
  35813.  
  35814. æKY NewHandleSysClear
  35815. æFc Memory.h
  35816. æT Function
  35817. æD pascal Handle NewHandleSysClear(Size byteCount); 
  35818. æDT Handle myVariable = NewHandleSysClear((Size) byteCount);
  35819. æRT 219
  35820. æC 
  35821. Trap macro  _NewHandle
  35822.             _NewHandle ,SYS        (applies to system heap)
  35823.             _NewHandle ,CLEAR      (clears allocated block)
  35824.             _NewHandle ,SYS,CLEAR  (applies to system heap and clears
  35825.                                     allocated block)
  35826. On entry    D0:  logicalSize (long word)
  35827. On exit     A0:  function result (handle)
  35828.             D0:  result code (word)
  35829.  
  35830. NewHandle attempts to allocate a new relocatable block of logicalSize bytes from the
  35831. current heap zone and then return a handle to it. The new block will be unlocked and
  35832. unpurgeable. If logicalSize bytes can’t be allocated, NewHandle returns NIL.
  35833.  
  35834. NewHandle will pursue all available avenues to create a free block of the requested
  35835. size, including compacting the heap zone, increasing its size, purging blocks from
  35836. it, and calling its grow zone function, if any.
  35837.  
  35838. Result codes    noErr         No error
  35839.                 memFullErr    Not enough room in heap zone
  35840.  
  35841. æKY HandleZone
  35842. æFc Memory.h
  35843. æT Function
  35844. æD pascal THz HandleZone(Handle h); 
  35845. æDT THz myVariable = HandleZone((Handle) h);
  35846. æRI II-34
  35847. æC 
  35848. Trap macro  _HandleZone
  35849. On entry    A0:  h (handle)
  35850. On exit     A0:  function result (pointer)
  35851.             D0:  result code (word)
  35852.  
  35853. HandleZone returns a pointer to the heap zone containing the relocatable block whose
  35854. handle is h. In case of an error, the result returned by HandleZone is undefined and
  35855. should be ignored.
  35856.  
  35857. Warning:  If handle h is empty (points to a NIL master pointer), HandleZone
  35858.           returns a pointer to the current heap zone.
  35859.  
  35860. Result codes    noErr       No error
  35861.                 memWZErr    Attempt to operate on a free block
  35862.  
  35863. æKY RecoverHandle
  35864. æFc Memory.h
  35865. æT Function
  35866. æD pascal Handle RecoverHandle(Ptr p); 
  35867. æDT Handle myVariable = RecoverHandle((Ptr) p);
  35868. æMM
  35869. æRT 23
  35870. æRI II-35, N8-1, N23-1
  35871. æC 
  35872. Trap macro  _RecoverHandle
  35873.             _RecoverHandle ,SYS  (applies to system heap)
  35874. On entry    A0:  p (pointer)
  35875. On exit     A0:  function result (handle)
  35876.             D0:  unchanged
  35877.  
  35878. RecoverHandle returns a handle to the relocatable block pointed to by p.
  35879.  
  35880. Assembly-language note:  The trap _RecoverHandle doesn’t return a result
  35881.                          code in register D0; the previous contents of D0
  35882.                          are preserved unchanged.
  35883.  
  35884. Result codes    noErr    No error [Pascal only]
  35885.  
  35886. æKY NewPtr
  35887. æFc Memory.h
  35888. æT Function
  35889. æD pascal Ptr NewPtr(Size byteCount); 
  35890. æDT Ptr myVariable = NewPtr((Size) byteCount);
  35891. æMM
  35892. æRI I-75, 79, II-36, P-51, 177
  35893. æC 
  35894. Trap macro  _NewPtr
  35895.             _NewPtr ,SYS        (applies to system heap)
  35896.             _NewPtr ,CLEAR      (clears allocated block)
  35897.             _NewPtr ,SYS,CLEAR  (applies to system heap and clears
  35898.                                  allocated block)
  35899. On entry    D0:  logicalSize (long word)
  35900. On exit     A0:  function result (pointer)
  35901.             D0:  result code (word)
  35902.  
  35903. NewPtr attempts to allocate a new nonrelocatable block of logicalSize bytes from the
  35904. current heap zone and then return a pointer to it. If logicalSize bytes can’t be
  35905. allocated, NewPtr returns NIL.
  35906.  
  35907. NewPtr will pursue all available avenues to create a free block of the requested size
  35908. at the lowest possible location in the heap zone, including compacting the heap zone,
  35909. increasing its size, purging blocks from it, and calling its grow zone function, if
  35910. any.
  35911.  
  35912. Result codes    noErr         No error
  35913.                 memFullErr    Not enough room in heap zone
  35914.  
  35915. æKY NewPtrSys
  35916. æFc Memory.h
  35917. æT Function
  35918. æD pascal Ptr NewPtrSys(Size byteCount); 
  35919. æDT Ptr myVariable = NewPtrSys((Size) byteCount);
  35920. æRT 219
  35921. æC 
  35922. Trap macro  _NewPtr
  35923.             _NewPtr ,SYS        (applies to system heap)
  35924.             _NewPtr ,CLEAR      (clears allocated block)
  35925.             _NewPtr ,SYS,CLEAR  (applies to system heap and clears
  35926.                                  allocated block)
  35927. On entry    D0:  logicalSize (long word)
  35928. On exit     A0:  function result (pointer)
  35929.             D0:  result code (word)
  35930.  
  35931. NewPtr attempts to allocate a new nonrelocatable block of logicalSize bytes from the
  35932. current heap zone and then return a pointer to it. If logicalSize bytes can’t be
  35933. allocated, NewPtr returns NIL.
  35934.  
  35935. NewPtr will pursue all available avenues to create a free block of the requested size
  35936. at the lowest possible location in the heap zone, including compacting the heap zone,
  35937. increasing its size, purging blocks from it, and calling its grow zone function, if
  35938. any.
  35939.  
  35940. Result codes    noErr         No error
  35941.                 memFullErr    Not enough room in heap zone
  35942.  
  35943. æKY NewPtrClear
  35944. æFc Memory.h
  35945. æT Function
  35946. æD pascal Ptr NewPtrClear(Size byteCount); 
  35947. æDT Ptr myVariable = NewPtrClear((Size) byteCount);
  35948. æRT 219
  35949. æC 
  35950. Trap macro  _NewPtr
  35951.             _NewPtr ,SYS        (applies to system heap)
  35952.             _NewPtr ,CLEAR      (clears allocated block)
  35953.             _NewPtr ,SYS,CLEAR  (applies to system heap and clears
  35954.                                  allocated block)
  35955. On entry    D0:  logicalSize (long word)
  35956. On exit     A0:  function result (pointer)
  35957.             D0:  result code (word)
  35958.  
  35959. NewPtr attempts to allocate a new nonrelocatable block of logicalSize bytes from the
  35960. current heap zone and then return a pointer to it. If logicalSize bytes can’t be
  35961. allocated, NewPtr returns NIL.
  35962.  
  35963. NewPtr will pursue all available avenues to create a free block of the requested size
  35964. at the lowest possible location in the heap zone, including compacting the heap zone,
  35965. increasing its size, purging blocks from it, and calling its grow zone function, if
  35966. any.
  35967.  
  35968. Result codes    noErr         No error
  35969.                 memFullErr    Not enough room in heap zone
  35970.  
  35971. æKY NewPtrSysClear
  35972. æFc Memory.h
  35973. æT Function
  35974. æD pascal Ptr NewPtrSysClear(Size byteCount); 
  35975. æDT Ptr myVariable = NewPtrSysClear((Size) byteCount);
  35976. æRT 219
  35977. æC 
  35978. Trap macro  _NewPtr
  35979.             _NewPtr ,SYS        (applies to system heap)
  35980.             _NewPtr ,CLEAR      (clears allocated block)
  35981.             _NewPtr ,SYS,CLEAR  (applies to system heap and clears
  35982.                                  allocated block)
  35983. On entry    D0:  logicalSize (long word)
  35984. On exit     A0:  function result (pointer)
  35985.             D0:  result code (word)
  35986.  
  35987. NewPtr attempts to allocate a new nonrelocatable block of logicalSize bytes from the
  35988. current heap zone and then return a pointer to it. If logicalSize bytes can’t be
  35989. allocated, NewPtr returns NIL.
  35990.  
  35991. NewPtr will pursue all available avenues to create a free block of the requested size
  35992. at the lowest possible location in the heap zone, including compacting the heap zone,
  35993. increasing its size, purging blocks from it, and calling its grow zone function, if
  35994. any.
  35995.  
  35996. Result codes    noErr         No error
  35997.                 memFullErr    Not enough room in heap zone
  35998.  
  35999. æKY PtrZone
  36000. æFc Memory.h
  36001. æT Function
  36002. æD pascal THz PtrZone(Ptr p); 
  36003. æDT THz myVariable = PtrZone((Ptr) p);
  36004. æRI II-38
  36005. æC 
  36006. Trap macro  _PtrZone
  36007. On entry    A0:  p (pointer)
  36008. On exit     A0:  function result (pointer)
  36009.             D0:  result code (word)
  36010.  
  36011. PtrZone returns a pointer to the heap zone containing the nonrelocatable block pointed
  36012. to by p. In case of an error, the result returned by PtrZone is undefined and should
  36013. be ignored.
  36014.  
  36015. Result codes    noErr       No error
  36016.                 memWZErr    Attempt to operate on a free block
  36017.  
  36018. æKY GZSaveHnd
  36019. æFc Memory.h
  36020. æT Function
  36021. æD pascal Handle GZSaveHnd(void)
  36022.     = {0x2EB8,0x0328}; 
  36023. æDT Handle myVariable = GZSaveHnd()(void);
  36024. æRI II-43
  36025. æC  
  36026. GZSaveHnd returns a handle to a relocatable block that must not be moved by the grow
  36027. zone function, or NIL if there is no such block. Your grow zone function must be sure
  36028. to call GZSaveHnd; if a handle is returned, it must ensure that this block is not
  36029. moved.
  36030.  
  36031. Assembly-language note:  You can find the same handle in the global
  36032.                          variable GZRootHnd.
  36033.  
  36034. æKY TopMem
  36035. æFc Memory.h
  36036. æT Function
  36037. æD pascal Ptr TopMem(void)
  36038.     = {0x2EB8,0x0108}; 
  36039. æDT Ptr myVariable = TopMem()(void);
  36040. æRI II-44
  36041. æC  
  36042. [Not in ROM]
  36043.  
  36044. On a Macintosh 128K or 512K, TopMem returns a pointer to the end of RAM; on the
  36045. Macintosh XL, it returns a pointer to the end of the memory available for use by the
  36046. application.
  36047.  
  36048. Assembly-language note:  This value is stored in the global variable MemTop.
  36049.  
  36050. æKY MaxBlock
  36051. æFc Memory.h
  36052. æT Function
  36053. æD pascal long MaxBlock(void); 
  36054. æDT long myVariable = MaxBlock()(void);
  36055. æRI IV-77
  36056. æC 
  36057. Trap macro  _MaxBlock
  36058.             _MaxBlock ,SYS    (applies to system heap)
  36059. On exit     D0:  function result (word)
  36060.  
  36061. MaxBlock returns the maximum contiguous space in bytes that could be obtained by
  36062. compacting the current zone (without actually doing the compaction).
  36063.  
  36064. æKY StackSpace
  36065. æFc Memory.h
  36066. æT Function
  36067. æD pascal long StackSpace(void); 
  36068. æDT long myVariable = StackSpace()(void);
  36069. æRI IV-78
  36070. æC 
  36071. Trap macro  _StackSpace
  36072. On exit     D0:  function result (word)
  36073.  
  36074. StackSpace returns the current amount of stack space between the current stack pointer
  36075. and the application heap (at the instant of return from the trap).
  36076.  
  36077. æKY NewEmptyHandle
  36078. æFc Memory.h
  36079. æT Function
  36080. æD pascal Handle NewEmptyHandle(void); 
  36081. æDT Handle myVariable = NewEmptyHandle()(void);
  36082. æMM
  36083. æRI IV-78
  36084. æC 
  36085. Trap macro  _NewEmptyHandle
  36086.             _NewEmptyHandle ,SYS    (applies to system heap)
  36087. On exit     A0:  function result (handle)
  36088.             D0:  result code (word)
  36089.  
  36090. NewEmptyHandle is similar in function to NewHandle except that it does not allocate
  36091. any space; the handle returned is empty (in other words, it points to a NIL master
  36092. pointer). NewEmptyHandle is used extensively by the Resource Manager; you may not
  36093. need to use it.
  36094.  
  36095. æKY HLock
  36096. æFc Memory.h
  36097. æT Function
  36098. æD pascal void HLock(Handle h); 
  36099. æDT HLock((Handle) h);
  36100. æRT 2
  36101. æRI II-41, N2-3
  36102. æC 
  36103. The master pointer associated with each handle contains flags for use by the Memory
  36104. Manager. Routines are provided for setting and clearing each of these flags, as well
  36105. as for saving and restoring the entire byte.
  36106.  
  36107. Warning:  Failure to use these routines virtually guarantees incompatibility
  36108.           with future versions of the Macintosh. You should not set and clear
  36109.           these flags directly.
  36110.  
  36111. The HLock and HUnlock procedures lock and unlock a given relocatable block by setting
  36112. and clearing the lock flag. The HPurge and HNoPurge mark a given relocatable block as
  36113. purgeable or unpurgeable by setting and clearing the purge flag.
  36114.  
  36115. A third flag, the resource flag, is used internally by the Resource Manager. The
  36116. HSetRBit and HClrRBit procedures set and clear this flag.
  36117. The HSetState and HGetState routines let you save and restore the state of the flags
  36118. byte.
  36119.  
  36120. PROCEDURE HLock (h:  Handle);
  36121.  
  36122. Trap macro  _HLock
  36123. On entry    A0:  h (handle)
  36124. On exit     D0:  result code (word)
  36125.  
  36126. HLock locks a relocatable block, preventing it from being moved within its heap zone.
  36127. If the block is already locked, HLock does nothing.
  36128.  
  36129. Warning:  To prevent heap fragmentation, you should always call MoveHHi
  36130.           before locking a relocatable block.
  36131.  
  36132. Result codes    noErr           No error
  36133.                 nilHandleErr    NIL master pointer
  36134.                 memWZErr        Attempt to operate on a free block
  36135.  
  36136. æKY HUnlock
  36137. æFc Memory.h
  36138. æT Function
  36139. æD pascal void HUnlock(Handle h); 
  36140. æDT HUnlock((Handle) h);
  36141. æRT 2
  36142. æRI II-41, N2-3
  36143. æC 
  36144. The master pointer associated with each handle contains flags for use by the Memory
  36145. Manager. Routines are provided for setting and clearing each of these flags, as well
  36146. as for saving and restoring the entire byte.
  36147.  
  36148. Warning:  Failure to use these routines virtually guarantees incompatibility
  36149.           with future versions of the Macintosh. You should not set and clear
  36150.           these flags directly.
  36151.  
  36152. The HLock and HUnlock procedures lock and unlock a given relocatable block by setting
  36153. and clearing the lock flag. The HPurge and HNoPurge mark a given relocatable block as
  36154. purgeable or unpurgeable by setting and clearing the purge flag.
  36155.  
  36156. A third flag, the resource flag, is used internally by the Resource Manager. The
  36157. HSetRBit and HClrRBit procedures set and clear this flag.
  36158. The HSetState and HGetState routines let you save and restore the state of the flags
  36159. byte.
  36160.  
  36161. PROCEDURE HUnlock (h:  Handle);
  36162.  
  36163. Trap macro  _HUnlock
  36164. On entry    A0:  h (handle)
  36165. On exit     D0:  result code (word)
  36166.  
  36167. HUnlock unlocks a relocatable block, allowing it to be moved within its heap zone. If
  36168. the block is already unlocked, HUnlock does nothing.
  36169.  
  36170. Result codes    noErr           No error
  36171.                 nilHandleErr    NIL master pointer
  36172.                 memWZErr        Attempt to operate on a free block
  36173.  
  36174. æKY HPurge
  36175. æFc Memory.h
  36176. æT Function
  36177. æD pascal void HPurge(Handle h); 
  36178. æDT HPurge((Handle) h);
  36179. æRT 2
  36180. æRI II-41
  36181. æC 
  36182. Trap macro  _HPurge
  36183. On entry    A0:  h (handle)
  36184. On exit     D0:  result code (word)
  36185.  
  36186. HPurge marks a relocatable block as purgeable. If the block is already purgeable,
  36187. HPurge does nothing.
  36188.  
  36189. Note:  If you call HPurge on a locked block, it won’t unlock the block, but
  36190.        it will mark the block as purgeable. If you later call HUnlock, the
  36191.        block will be subject to purging.
  36192.  
  36193. Result codes    noErr           No error
  36194.                 nilHandleErr    NIL master pointer
  36195.                 memWZErr        Attempt to operate on a free block
  36196.  
  36197. æKY HNoPurge
  36198. æFc Memory.h
  36199. æT Function
  36200. æD pascal void HNoPurge(Handle h); 
  36201. æDT HNoPurge((Handle) h);
  36202. æRT 2
  36203. æRI II-42, N2-3
  36204. æC 
  36205. Trap macro  _HNoPurge
  36206. On entry    A0:  h (handle)
  36207. On exit     D0:  result code (word)
  36208.  
  36209. HNoPurge marks a relocatable block as unpurgeable. If the block is already unpurgeable,
  36210. HNoPurge does nothing.
  36211.  
  36212. Result codes    noErr           No error
  36213.                 nilHandleErr    NIL master pointer
  36214.                 memWZErr        Attempt to operate on a free block
  36215.  
  36216. æKY StripAddress
  36217. æFc Memory.h
  36218. æT Function
  36219. æD pascal Ptr StripAddress(Ptr theAddress); 
  36220. æDT Ptr myVariable = StripAddress((Ptr) theAddress);
  36221. æRT 212,213
  36222. æRI V-593
  36223. æC 
  36224. Trap macro  _StripAddress
  36225. On entry    D0:  theAddress (pointer)
  36226. On exit     D0:  function result (pointer)
  36227.  
  36228. The original description of StripAddress was incorrect.  Technical Note #213 correctly
  36229. documents this function.
  36230.  
  36231. •••Refer to Technical Note #213:•••
  36232.  
  36233. æKY MFMaxMem
  36234. æFc Memory.h
  36235. æT Function
  36236. æTN A88F
  36237. æD pascal Size MFMaxMem(Size *grow)
  36238.     = {0x3F3C,0x0015,0xA88F}; 
  36239. æDT Size myVariable = MFMaxMem((Size *) grow);
  36240. æC 
  36241.  
  36242. æKY MFFreeMem
  36243. æFc Memory.h
  36244. æT Function
  36245. æTN A88F
  36246. æD pascal long MFFreeMem(void)
  36247.     = {0x3F3C,0x0018,0xA88F}; 
  36248. æDT long myVariable = MFFreeMem()(void);
  36249. æC 
  36250.  
  36251. æKY MFTempNewHandle
  36252. æFc Memory.h
  36253. æT Function
  36254. æTN A88F
  36255. æD pascal Handle MFTempNewHandle(Size logicalSize,OSErr *resultCode)
  36256.     = {0x3F3C,0x001D,0xA88F}; 
  36257. æDT Handle myVariable = MFTempNewHandle((Size) logicalSize,(OSErr *) resultCode);
  36258. æRT 205
  36259. æC 
  36260.  
  36261. æKY MFTempHLock
  36262. æFc Memory.h
  36263. æT Function
  36264. æTN A88F
  36265. æD pascal void MFTempHLock(Handle h,OSErr *resultCode)
  36266.     = {0x3F3C,0x001E,0xA88F}; 
  36267. æDT MFTempHLock((Handle) h,(OSErr *) resultCode);
  36268. æC 
  36269.  
  36270. æKY MFTempHUnlock
  36271. æFc Memory.h
  36272. æT Function
  36273. æTN A88F
  36274. æD pascal void MFTempHUnlock(Handle h,OSErr *resultCode)
  36275.     = {0x3F3C,0x001F,0xA88F}; 
  36276. æDT MFTempHUnlock((Handle) h,(OSErr *) resultCode);
  36277. æC 
  36278.  
  36279. æKY MFTempDisposHandle
  36280. æFc Memory.h
  36281. æT Function
  36282. æTN A88F
  36283. æD pascal void MFTempDisposHandle(Handle h,OSErr *resultCode)
  36284.     = {0x3F3C,0x0020,0xA88F}; 
  36285. æDT MFTempDisposHandle((Handle) h,(OSErr *) resultCode);
  36286. æC 
  36287.  
  36288. æKY MFTopMem
  36289. æFc Memory.h
  36290. æT Function
  36291. æTN A88F
  36292. æD pascal Ptr MFTopMem(void)
  36293.     = {0x3F3C,0x0016,0xA88F}; 
  36294. æDT Ptr myVariable = MFTopMem()(void);
  36295. æC 
  36296.  
  36297. æKY InitApplZone
  36298. æFc Memory.h
  36299. æT Function
  36300. æTN A02C
  36301. æD pascal void InitApplZone(void)
  36302.     = 0xA02C; 
  36303. æDT InitApplZone()(void);
  36304. æMM
  36305. æRI II-28, N64-2
  36306. æC 
  36307. Trap macro   _InitApplZone
  36308. On exit      D0:  result code (word)
  36309.  
  36310. InitApplZone initializes the application heap zone and makes it the current zone. The
  36311. contents of any previous application zone are lost; all previously existing blocks in
  36312. that zone are discarded. The zone’s grow zone function is set to NIL. InitApplZone is
  36313. called by the Segment Loader when starting up an application; you shouldn’t normally
  36314. need to call it.
  36315.  
  36316. Warning:  Reinitializing the application zone from within a running program
  36317.           is tricky, since the program’s code itself normally resides in the
  36318.           application zone. To do it safely, the code containing the
  36319.           InitApplZone call cannot be in the application zone.
  36320.  
  36321. Result codes    noErr    No error
  36322.  
  36323. æKY InitZone
  36324. æFc Memory.h
  36325. æT Function
  36326. æD pascal void InitZone(GrowZoneProcPtr pgrowZone,short cmoreMasters,Ptr limitPtr,
  36327.     Ptr startPtr); 
  36328. æDT InitZone((GrowZoneProcPtr) pgrowZone,(short) cmoreMasters,(Ptr) limitPtr,()
  36329.     Ptr startPtr);
  36330. æMM
  36331. æRI II-29
  36332. æC 
  36333. Trap macro  _InitZone
  36334. On entry    A0:    pointer to parameter block
  36335.  
  36336. Parameter block
  36337.     0    startPtr      pointer
  36338.     4    limitPtr      pointer
  36339.     8    cMoreMasters  word
  36340.     10   pGrowZone     pointer
  36341.  
  36342. On exit     D0:    result code (word)
  36343.  
  36344. InitZone creates a new heap zone, initializes its header and trailer, and makes it
  36345. the current zone. The startPtr parameter is a pointer to the first byte of the new
  36346. zone; limitPtr points to the first byte beyond the end of the zone. The new zone will
  36347. occupy memory addresses from ORD(startPtr) through
  36348. ORD(limitPtr)–1.
  36349.  
  36350. CMoreMasters tells how many master pointers should be allocated at a time for the new
  36351. zone. This number of master pointers are created initially; should more be needed
  36352. later, they’ll be added in increments of this same number.
  36353.  
  36354. The pGrowZone parameter is a pointer to the grow zone function for the new zone, if
  36355. any. If you’re not defining a grow zone function for this zone, pass NIL.
  36356.  
  36357. The new zone includes a 52-byte header and a 12-byte trailer, so its actual usable
  36358. space runs from ORD(startPtr)+52 through ORD(limitPtr)–13. In addition, there’s an
  36359. eight-byte header for the master pointer block, as well as four bytes for each master
  36360. pointer, within this usable area. Thus the total available space in the zone, in
  36361. bytes, is initially
  36362.  
  36363.   ORD(limitPtr) – ORD(startPtr) – 64 – (8 + (4*cMoreMasters))
  36364.  
  36365. This number must not be less than 0. Note that the amount of available space in the
  36366. zone will decrease as more master pointers are allocated.
  36367.  
  36368. Result codes    noErr    No error
  36369.  
  36370. æKY SetZone
  36371. æFc Memory.h
  36372. æT Function
  36373. æD pascal void SetZone(THz hz); 
  36374. æDT SetZone((THz) hz);
  36375. æRI II-31, N8-1
  36376. æC 
  36377. Trap macro  _SetZone
  36378. On entry    A0:  hz (pointer)
  36379. On exit     D0:  result code (word)
  36380.  
  36381. SetZone sets the current heap zone to the zone pointed to by hz.
  36382.  
  36383. Assembly-language note:  You can set the current heap zone by storing
  36384.                          a pointer to it in the global variable TheZone.
  36385.  
  36386. Result codes    noErr    No error
  36387.  
  36388. æKY CompactMem
  36389. æFc Memory.h
  36390. æT Function
  36391. æD pascal Size CompactMem(Size cbNeeded); 
  36392. æDT Size myVariable = CompactMem((Size) cbNeeded);
  36393. æMM
  36394. æRT 51
  36395. æRI II-39, N51-1
  36396. æC 
  36397. Trap macro  _CompactMem
  36398.             _CompactMem ,SYS (applies to system heap)
  36399. On entry    D0:  cbNeeded (long word)
  36400. On exit     D0:  function result (long word)
  36401.  
  36402. CompactMem compacts the current heap zone by moving relocatable blocks down and
  36403. collecting free space together until a contiguous block of at least cbNeeded free
  36404. bytes is found or the entire zone is compacted; it doesn’t purge any purgeable blocks.
  36405. CompactMem returns the size in bytes of the largest contiguous free block remaining.
  36406. Note that it doesn’t actually allocate the block.
  36407.  
  36408. Result codes    noErr    No error [Pascal only]
  36409.  
  36410. æKY PurgeMem
  36411. æFc Memory.h
  36412. æT Function
  36413. æD pascal void PurgeMem(Size cbNeeded); 
  36414. æDT PurgeMem((Size) cbNeeded);
  36415. æMM
  36416. æRT 51
  36417. æRI II-40, N51-1
  36418. æC 
  36419. Trap macro  _PurgeMem
  36420.             _PurgeMem ,SYS (applies to system heap)
  36421. On entry    D0:  cbNeeded (long word)
  36422. On exit     D0:  result code (word)
  36423.  
  36424. PurgeMem sequentially purges blocks from the current heap zone until a contiguous
  36425. block of at least cbNeeded free bytes is created or the entire zone is purged; it
  36426. doesn’t compact the heap zone. Only relocatable, unlocked, purgeable blocks can be
  36427. purged. Note that PurgeMem doesn’t actually allocate the block.
  36428.  
  36429. Result codes    noErr         No error
  36430.                 memFullErr    Not enough room in heap zone
  36431.  
  36432. æKY FreeMem
  36433. æFc Memory.h
  36434. æT Function
  36435. æD pascal long FreeMem(void); 
  36436. æDT long myVariable = FreeMem()(void);
  36437. æMM
  36438. æRI II-38
  36439. æC 
  36440. Trap macro  _FreeMem
  36441.             _FreeMem ,SYS (applies to system heap)
  36442. On exit     D0:  function result (long word)
  36443.  
  36444. FreeMem returns the total amount of free space in the current heap zone, in bytes.
  36445. Note that it usually isn’t possible to allocate a block of this size, because of
  36446. fragmentation due to nonrelocatable or locked blocks.
  36447.  
  36448. Result codes    noErr    No error [Pascal only]
  36449.  
  36450. æKY ResrvMem
  36451. æFc Memory.h
  36452. æT Function
  36453. æD pascal void ResrvMem(Size cbNeeded); 
  36454. æDT ResrvMem((Size) cbNeeded);
  36455. æMM
  36456. æRI II-39
  36457. æC 
  36458. Trap macro  _ResrvMem
  36459.             _ResrvMem ,SYS (applies to system heap)
  36460. On entry    D0:  cbNeeded (long word)
  36461. On exit     D0:  result code (word)
  36462.  
  36463. ResrvMem creates free space for a block of cbNeeded contiguous bytes at the lowest
  36464. possible position in the current heap zone. It will try every available means to
  36465. place the block as close as possible to the bottom of the zone, including moving
  36466. other blocks upward, expanding the zone, or purging blocks from it. Note that ResrvMem
  36467. doesn’t actually allocate the block.
  36468.  
  36469. Note:  When you allocate a relocatable block that you know will be locked for
  36470.        long periods of time, call ResrvMem first. This reserves space for the
  36471.        block near the bottom of the heap zone, where it will interfere with
  36472.        compaction as little as possible. It isn’t necessary to call ResrvMem
  36473.        for a nonrelocatable block; NewPtr calls it automatically. It’s also
  36474.        called automatically when locked resources are read into memory.
  36475.  
  36476. Result codes    noErr         No error
  36477.                 memFullErr    Not enough room in heap zone
  36478.  
  36479. æKY MaxMem
  36480. æFc Memory.h
  36481. æT Function
  36482. æD pascal Size MaxMem(Size *grow); 
  36483. æDT Size myVariable = MaxMem((Size *) grow);
  36484. æRI II-38
  36485. æC 
  36486. Trap macro  _MaxMem
  36487.             _MaxMem ,SYS (applies to system heap)
  36488. On exit     D0:  function result (long word)
  36489.             A0:  grow (long word)
  36490.  
  36491. MaxMem compacts the current heap zone and purges all purgeable blocks from the zone.
  36492. It returns as its result the size in bytes of the largest contiguous free block in
  36493. the zone after the compaction. If the current zone is the original application heap
  36494. zone, the grow parameter is set to the maximum number of bytes by which the zone can
  36495. grow. For any other heap zone, grow is set to 0. MaxMem doesn’t actually expand the
  36496. zone or call its grow zone function.
  36497.  
  36498. Result codes    noErr    No error [Pascal only]
  36499.  
  36500. æKY SetGrowZone
  36501. æFc Memory.h
  36502. æT Function
  36503. æD pascal void SetGrowZone(GrowZoneProcPtr growZone); 
  36504. æDT SetGrowZone((GrowZoneProcPtr) growZone);
  36505. æRI II-42
  36506. æC 
  36507. Trap macro  _SetGrowZone
  36508. On entry    A0:  growZone (pointer)
  36509. On exit     D0:  result code (word)
  36510.  
  36511. SetGrowZone sets the current heap zone’s grow zone function as designated by the
  36512. growZone parameter. A NIL parameter value removes any grow zone function the zone may
  36513. previously have had.
  36514.  
  36515. Note:  If your program presses the limits of the available heap space, it’s
  36516.        a good idea to have a grow zone function of some sort. At the very
  36517.        least, the grow zone function should take some graceful action—such
  36518.        as displaying an alert box with the message “Out of memory”—instead
  36519.       of just failing unpredictably.
  36520.  
  36521. If it has failed to create a block of the needed size after compacting the zone,
  36522. increasing its size (in the case of the original application zone), and purging
  36523. blocks from it, the Memory Manager calls the grow zone function as a last resort.
  36524.  
  36525. The grow zone function should be of the form
  36526.  
  36527. FUNCTION MyGrowZone (cbNeeded:  Size) :  LONGINT;
  36528.  
  36529. The cbNeeded parameter gives the physical size of the needed block in bytes, including
  36530. the block header. The grow zone function should attempt to create a free block of at
  36531. least this size. It should return a nonzero number if it’s able to allocate some
  36532. memory, or 0 if it’s not able to allocate any.
  36533.  
  36534. If the grow zone function returns 0, the Memory Manager will give up trying to allocate
  36535. the needed block and will signal failure with the result code memFullErr. Otherwise
  36536. it will compact the heap zone and try again to allocate the block. If still unsuccessful,
  36537. it will continue to call the grow zone function repeatedly, compacting the zone again
  36538. after each call, until it either succeeds in allocating the needed block or receives
  36539. a zero result and gives up.
  36540.  
  36541. The usual way for the grow zone function to free more space is to call EmptyHandle to
  36542. purge blocks that were previously marked unpurgeable. Another possibility is to
  36543. unlock blocks that were previously locked
  36544.  
  36545. Note:  Although just unlocking blocks doesn’t actually free any additional
  36546.        space in the zone, the grow zone function should still return a nonzero
  36547.        result in this case. This signals the Memory Manager to compact the
  36548.        heap and try again to allocate the needed block.
  36549.  
  36550. Warning:  Depending on the circumstances in which the grow zone function is
  36551.           called, there may be a particular block within the heap zone that
  36552.           must not be moved. For this reason, it’s essential that your grow
  36553.           zone function call the function GZSaveHnd (see below).
  36554.  
  36555. Result codes    noErr    No error
  36556.  
  36557. æKY SetApplLimit
  36558. æFc Memory.h
  36559. æT Function
  36560. æD pascal void SetApplLimit(Ptr zoneLimit); 
  36561. æDT SetApplLimit((Ptr) zoneLimit);
  36562. æRI II-30
  36563. æC 
  36564. Trap macro  _SetApplLimit
  36565. On entry    A0:  zoneLimit (pointer)
  36566. On exit     D0:  result code (word)
  36567.  
  36568. SetApplLimit sets the application heap limit, beyond which the application heap can’t
  36569. be expanded. The actual expansion isn’t under your program’s control, but is done
  36570. automatically by the Memory Manager when necessary to satisfy allocation requests.
  36571. Only the original application zone can be expanded.
  36572.  
  36573. ZoneLimit is a pointer to a byte in memory beyond which the zone will not be allowed
  36574. to grow. The zone can grow to include the byte preceding zoneLimit in memory, but no
  36575. farther. If the zone already extends beyond the specified limit it won’t be cut back,
  36576. but it will be prevented from growing any more.
  36577.  
  36578. Warning:  Notice that zoneLimit is not a byte count. To limit the application
  36579.           zone to a particular size (say 8K bytes), you have to write something
  36580.           like
  36581.  
  36582.             SetApplLimit(Ptr(ApplicZone)+8192)
  36583.  
  36584. The Memory Manager function ApplicZone is explained below.
  36585.  
  36586. Assembly-language note:  You can just store the new application heap
  36587.                          limit in the global variable ApplLimit.
  36588.  
  36589. Result codes    noErr         No error
  36590.                 memFullErr    Not enough room in heap zone
  36591.  
  36592. æKY MoveHHi
  36593. æFc Memory.h
  36594. æT Function
  36595. æD pascal void MoveHHi(Handle h); 
  36596. æDT MoveHHi((Handle) h);
  36597. æMM
  36598. æRT 103, 111
  36599. æRI II-44, IV-77, 83, N103, N111
  36600. æC 
  36601. [Not in 64K ROM]
  36602.  
  36603. Trap macro  _MoveHHi
  36604. On entry    A0:  h (handle)
  36605. On exit     D0:  result code (word)
  36606.  
  36607. MoveHHi moves the relocatable block whose handle is h toward the top of the current
  36608. heap zone, until the block hits either a nonrelocatable block, a locked relocatable
  36609. block, or the last block in the current heap zone. By calling MoveHHi before you lock
  36610. a relocatable block, you can avoid fragmentation of the heap, as well as make room
  36611. for future pointers as low in the heap as possible.
  36612.  
  36613. Result codes    noErr           No error
  36614.                 nilHandleErr    NIL master pointer
  36615.                 memLockedErr    Block is locked
  36616.  
  36617. æKY DisposPtr
  36618. æFc Memory.h
  36619. æT Function
  36620. æD pascal void DisposPtr(Ptr p); 
  36621. æDT DisposPtr((Ptr) p);
  36622. æMM
  36623. æRI I-75, 79, II-36, P-51, 169
  36624. æC 
  36625. Trap macro  _DisposPtr
  36626. On entry    A0:  p (pointer)
  36627. On exit     D0:  result code (word)
  36628.  
  36629. DisposPtr releases the memory occupied by the nonrelocatable block pointed to by
  36630. p.
  36631.  
  36632. Warning:  After a call to DisposPtr, all pointers to the released block
  36633.           become invalid and should not be used again. Any subsequent calls
  36634.           to DisposPtr using an invalid pointer will damage the master
  36635.           pointer list.
  36636.  
  36637. Result codes    noErr       No error
  36638.                 memWZErr    Attempt to operate on a free block
  36639.  
  36640. æKY GetPtrSize
  36641. æFc Memory.h
  36642. æT Function
  36643. æD pascal Size GetPtrSize(Ptr p); 
  36644. æDT Size myVariable = GetPtrSize((Ptr) p);
  36645. æRI II-37
  36646. æC 
  36647. Trap macro  _GetPtrSize
  36648. On entry    A0:    p (pointer)
  36649. On exit     D0:    if >= 0, function result (long word)
  36650.                    if < 0, result code (word)
  36651.  
  36652. GetPtrSize returns the logical size, in bytes, of the nonrelocatable block pointed to
  36653. by p. In case of an error, GetPtrSize returns 0.
  36654.  
  36655. Assembly-language note:  Recall that the trap dispatcher sets the condition
  36656.                          codes before returning from a trap by testing the
  36657.                          low-order word of register D0 with a TST.W instruction.
  36658.                          Since the block size returned in D0 by _GetPtrSize is
  36659.                          a full 32-bit long word, the word-length test sets the
  36660.                          condition codes incorrectly in this case. To branch on
  36661.                          the contents of D0, use your own TST.L instruction on
  36662.                          return from the trap to test the full 32 bits of the
  36663.                          register.
  36664.  
  36665. Result codes    noErr       No error [Pascal only]
  36666.                 memWZErr    Attempt to operate on a free block
  36667.  
  36668. æKY SetPtrSize
  36669. æFc Memory.h
  36670. æT Function
  36671. æD pascal void SetPtrSize(Ptr p,Size newSize); 
  36672. æDT SetPtrSize((Ptr) p,(Size) newSize);
  36673. æMM
  36674. æRI II-37
  36675. æC 
  36676. Trap macro  _SetPtrSize
  36677. On entry    A0:  p (pointer)
  36678.             D0:  newSize (long word)
  36679. On exit     D0:  result code (word)
  36680.  
  36681. SetPtrSize changes the logical size of the nonrelocatable block pointed to by p to
  36682. newSize bytes.
  36683.  
  36684. Result codes    noErr         No error
  36685.                 memFullErr    Not enough room in heap zone
  36686.                 memWZErr      Attempt to operate on a free block
  36687.  
  36688. æKY DisposHandle
  36689. æFc Memory.h
  36690. æT Function
  36691. æD pascal void DisposHandle(Handle h); 
  36692. æDT DisposHandle((Handle) h);
  36693. æMM
  36694. æRI I-76, 80, II-33, N8-1, P-51, 168
  36695. æC 
  36696. Trap macro  _DisposHandle
  36697. On entry    A0:  h (handle)
  36698. On exit     D0:  result code (word)
  36699.  
  36700. DisposHandle releases the memory occupied by the relocatable block whose handle is
  36701. h.
  36702.  
  36703. Warning:  After a call to DisposHandle, all handles to the released block
  36704.           become invalid and should not be used again. Any subsequent calls
  36705.           to DisposHandle using an invalid handle will damage the master
  36706.           pointer list.
  36707.  
  36708. Result codes    noErr       No error
  36709.                 memWZErr    Attempt to operate on a free block
  36710.  
  36711. æKY GetHandleSize
  36712. æFc Memory.h
  36713. æT Function
  36714. æD pascal Size GetHandleSize(Handle h); 
  36715. æDT Size myVariable = GetHandleSize((Handle) h);
  36716. æRI II-33, N54-1, N63-1
  36717. æC 
  36718. Trap macro  _GetHandleSize
  36719. On entry    A0:    h (handle)
  36720. On exit     D0:    if >= 0, function result (long word)
  36721.                    if < 0, result code (word)
  36722.  
  36723. GetHandleSize returns the logical size, in bytes, of the relocatable block whose
  36724. handle is h. In case of an error, GetHandleSize returns 0.
  36725.  
  36726. Assembly-language note:  Recall that the trap dispatcher sets the condition
  36727.                          codes before returning from a trap by testing the
  36728.                          low-order word of register D0 with a TST.W instruction.
  36729.                          Since the block size returned in D0 by _GetHandleSize
  36730.                          is a full 32-bit long word, the word-length test sets
  36731.                          the condition codes incorrectly in this case. To
  36732.                          branch on the contents of D0, use your own TST.L
  36733.                          instruction on return from the trap to test the full
  36734.                          32 bits of the register.
  36735.  
  36736. Result codes    noErr           No error [Pascal only]
  36737.                 nilHandleErr    NIL master pointer
  36738.                 memWZErr        Attempt to operate on a free block
  36739.  
  36740. æKY SetHandleSize
  36741. æFc Memory.h
  36742. æT Function
  36743. æD pascal void SetHandleSize(Handle h,Size newSize); 
  36744. æDT SetHandleSize((Handle) h,(Size) newSize);
  36745. æMM
  36746. æRI II-34
  36747. æC 
  36748. Trap macro  _SetHandleSize
  36749. On entry    A0:  h (handle)
  36750.             D0:  newSize (long word)
  36751. On exit     D0:  result code (word)
  36752.  
  36753. SetHandleSize changes the logical size of the relocatable block whose handle is h to
  36754. newSize bytes.
  36755.  
  36756. Note:  Be prepared for an attempt to increase the size of a locked block to
  36757.        fail, since there may be a block above it that’s either nonrelocatable
  36758.        or locked.
  36759.  
  36760. Result codes    noErr           No error
  36761.                 memFullErr      Not enough room in heap zone
  36762.                 nilHandleErr    NIL master pointer
  36763.                 memWZErr        Attempt to operate on a free block
  36764.  
  36765. æKY EmptyHandle
  36766. æFc Memory.h
  36767. æT Function
  36768. æD pascal void EmptyHandle(Handle h); 
  36769. æDT EmptyHandle((Handle) h);
  36770. æMM
  36771. æRI II-40
  36772. æC 
  36773. Trap macro  _EmptyHandle
  36774. On entry    A0:  h (handle)
  36775. On exit     A0:  h (handle)
  36776.             D0:  result code (word)
  36777.  
  36778. EmptyHandle purges the relocatable block whose handle is h from its heap zone and
  36779. sets its master pointer to NIL (making it an empty handle). If h is already empty,
  36780. EmptyHandle does nothing.
  36781.  
  36782. Note:  Since the space occupied by the block’s master pointer itself remains
  36783.        allocated, all handles pointing to it remain valid but empty. When you
  36784.        later reallocate space for the block with ReallocHandle, the master
  36785.        pointer will be updated, causing all existing handles to access the
  36786.        new block correctly.
  36787.  
  36788. The block whose handle is h must be unlocked, but need not be purgeable.
  36789.  
  36790. Result codes    noErr        No error
  36791.                 memWZErr     Attempt to operate on a free block
  36792.                 memPurErr    Attempt to purge a locked block
  36793.  
  36794. æKY ReallocHandle
  36795. æFc Memory.h
  36796. æT Function
  36797. æD pascal void ReallocHandle(Handle h,Size byteCount); 
  36798. æDT ReallocHandle((Handle) h,(Size) byteCount);
  36799. æMM
  36800. æRI II-35
  36801. æC 
  36802. Trap macro  _ReallocHandle
  36803. On entry    A0:  h (handle)
  36804.             D0:  logicalSize (long word)
  36805. On exit     D0:  result code (word)
  36806.  
  36807. ReallocHandle allocates a new relocatable block with a logical size of logicalSize
  36808. bytes. It then updates handle h by setting its master pointer to point to the new
  36809. block. The main use of this procedure is to reallocate space for a block that has
  36810. been purged. Normally h is an empty handle, but it need not be:  If it points to an
  36811. existing block, that block is released before the new block is created.
  36812.  
  36813. In case of an error, no new block is allocated and handle h is left unchanged.
  36814.  
  36815. Result codes    noErr         No error
  36816.                 memFullErr    Not enough room in heap zone
  36817.                 memWZErr      Attempt to operate on a free block
  36818.                 memPurErr     Attempt to purge a locked block
  36819.  
  36820. æKY HSetRBit
  36821. æFc Memory.h
  36822. æT Function
  36823. æD pascal void HSetRBit(Handle h); 
  36824. æDT HSetRBit((Handle) h);
  36825. æRT 2
  36826. æRI IV-79, N2-3
  36827. æC 
  36828. Trap macro  _HSetRBit
  36829. On entry    A0:  h (handle)
  36830. On exit     D0:  result code (word)
  36831.  
  36832. HSetRBit sets the resource flag of a relocatable block’s master pointer.
  36833.  
  36834. æKY HClrRBit
  36835. æFc Memory.h
  36836. æT Function
  36837. æD pascal void HClrRBit(Handle h); 
  36838. æDT HClrRBit((Handle) h);
  36839. æRT 2
  36840. æRI IV-79, N2-3
  36841. æC 
  36842. Trap macro  _HClrRBit
  36843. On entry    A0:  h (handle)
  36844. On exit     D0:  result code (word)
  36845.  
  36846. HClrRBit clears the resource flag of a relocatable block’s master pointer.
  36847.  
  36848. æKY MoreMasters
  36849. æFc Memory.h
  36850. æT Function
  36851. æTN A036
  36852. æD pascal void MoreMasters(void)
  36853.     = 0xA036; 
  36854. æDT MoreMasters()(void);
  36855. æMM
  36856. æRT 53
  36857. æRI II-31, N53
  36858. æC 
  36859. Trap macro  _MoreMasters
  36860.  
  36861. MoreMasters allocates another block of master pointers in the current heap zone. This
  36862. procedure is usually called very early in an application.
  36863.  
  36864. Result codes    noErr         No error
  36865.                 memFullErr    Not enough room in heap zone
  36866.  
  36867. æKY BlockMove
  36868. æFc Memory.h
  36869. æT Function
  36870. æD pascal void BlockMove(Ptr srcPtr,Ptr destPtr,Size byteCount); 
  36871. æDT BlockMove((Ptr) srcPtr,(Ptr) destPtr,(Size) byteCount);
  36872. æRI II-44
  36873. æC 
  36874. Trap macro  _BlockMove
  36875. On entry    A0:  sourcePtr (pointer)
  36876.             A1:  destPtr (pointer)
  36877.             D0:  byteCount (long word)
  36878. On exit     D0:  result code (word)
  36879.  
  36880. BlockMove moves a block of byteCount consecutive bytes from the address designated by
  36881. sourcePtr to that designated by destPtr. No pointers are updated. BlockMove works
  36882. correctly even if the source and destination blocks overlap.
  36883.  
  36884. Result codes    noErr    No error
  36885.  
  36886. æKY MemError
  36887. æFc Memory.h
  36888. æT Function
  36889. æD pascal OSErr MemError(void)
  36890.     = {0x3EB8,0x0220}; 
  36891. æDT OSErr myVariable = MemError()(void);
  36892. æRT 7
  36893. æRI II-44, N7-2
  36894. æC  æC  
  36895. All Memory Manager routines (including the RecoverHandle function) return a result
  36896. code that you can examine by calling the MemError function.
  36897.  
  36898. Assembly-language note:  The trap _RecoverHandle doesn’t return a result code
  36899.                          in register D0. The result code of the most recent
  36900.                          call, however, is always stored in the global
  36901.                          variable MemErr.
  36902.  
  36903. FUNCTION MemError :  OSErr; [Not in ROM]
  36904.  
  36905. MemError returns the result code produced by the last Memory Manager routine called
  36906. directly by your program. (OSErr is an Operating System Utility data type declared as
  36907. INTEGER.)
  36908.  
  36909. Assemby-language note:  To get a routine’s result code from assembly language,
  36910.                         look in register D0 on return from the routine (except
  36911.                         for certain routines as noted).
  36912.  
  36913. æKY PurgeSpace
  36914. æFc Memory.h
  36915. æT Function
  36916. æD pascal void PurgeSpace(long *total,long *contig); 
  36917. æDT PurgeSpace((long *) total,(long *) contig);
  36918. æRI IV-78
  36919. æC 
  36920. Trap macro  _PurgeSpace
  36921.             _PurgeSpace ,SYS    (applies to system heap)
  36922. On exit     A0:  contig (long word)
  36923.             D0:  total (long word)
  36924.  
  36925. PurgeSpace returns in total the total amount of space in bytes that could be obtained
  36926. by a general purge (without actually doing the purge); this amount includes space
  36927. that is already free. The maximum contiguous space in bytes
  36928. (including already free space) that could be obtained by a purge is returned in
  36929. contig.
  36930.  
  36931. æKY HGetState
  36932. æFc Memory.h
  36933. æT Function
  36934. æD pascal char HGetState(Handle h); 
  36935. æDT char myVariable = HGetState((Handle) h);
  36936. æRT 2
  36937. æRI IV-79, N2-3
  36938. æC 
  36939. Trap macro  _HGetState
  36940. On entry    A0:  h (handle)
  36941. On exit     D0:  flags (byte)
  36942.  
  36943. HGetState returns the byte that contains the flags of the master pointer for the
  36944. given handle; it’s used in conjunction with HSetState to save and restore the state
  36945. of the flags contained in this byte. You can save this byte, change the state of any
  36946. of the flags (using the routines described above), and then restore their original
  36947. state by passing the byte back to the HSetState procedure (described below).
  36948.  
  36949. æKY HSetState
  36950. æFc Memory.h
  36951. æT Function
  36952. æD pascal void HSetState(Handle h,char flags); 
  36953. æDT HSetState((Handle) h,(char) flags);
  36954. æRT 2
  36955. æRI IV-80, N2-3
  36956. æC 
  36957. Trap macro  _HSetState
  36958. On entry    A0:  h (handle)
  36959.             D0:  flags (byte)
  36960. On exit     D0:  result code (word)
  36961.  
  36962. HSetState is used in conjunction with HGetState; it sets the byte that contains the
  36963. flags of the master pointer for the given handle to the byte specified by flags.
  36964.  
  36965. æKY SetApplBase
  36966. æFc Memory.h
  36967. æT Function
  36968. æD pascal void SetApplBase(Ptr startPtr); 
  36969. æDT SetApplBase((Ptr) startPtr);
  36970. æMM
  36971. æRI II-28
  36972. æC 
  36973. Trap macro  _SetAppBase
  36974. On entry    A0:  startPtr (pointer)
  36975. On exit     D0:  result code (word)
  36976.  
  36977. SetApplBase changes the starting address of the application heap zone to the address
  36978. designated by startPtr, and then calls InitApplZone. SetApplBase is normally called
  36979. only by the system itself; you should never need to call this procedure.
  36980.  
  36981. Since the application heap zone begins immediately following the end of the system
  36982. zone, changing its starting address has the effect of changing the size of the system
  36983. zone. The system zone can be made larger, but never smaller; if startPtr points to an
  36984. address lower than the current end of the system zone,
  36985. it’s ignored and the application zone’s starting address is left unchanged.
  36986.  
  36987. Warning:  Like InitApplZone, SetApplBase is a tricky operation, because the
  36988.           program’s code itself normally resides in the application heap zone.
  36989.           To do it safely, the code containing the SetApplBase call cannot be
  36990.           in the application zone.
  36991.  
  36992. Result codes    noErr    No error
  36993.  
  36994. æKY MaxApplZone
  36995. æFc Memory.h
  36996. æT Function
  36997. æTN A063
  36998. æD pascal void MaxApplZone(void)
  36999.     = 0xA063; 
  37000. æDT MaxApplZone()(void);
  37001. æRT 103
  37002. æRI II-30, IV-77, 83, N39-1, N103
  37003. æC 
  37004. Trap macro  _MaxApplZone
  37005. On exit     D0:  result code (word)
  37006.  
  37007. MaxApplZone expands the application heap zone to the application heap limit without
  37008. purging any blocks currently in the zone. If the zone already extends to the limit,
  37009. it won’t be changed.
  37010.  
  37011. Assembly-language note:  To expand the application heap zone to the
  37012.                          application heap limit from assembly language,
  37013.                          call this Pascal procedure from your program.
  37014.  
  37015. Result codes    noErr    No error
  37016.  
  37017.  
  37018. æKY Menus.h
  37019. æKL AddResMenu
  37020. AppendMenu
  37021. appendmenu
  37022. CalcMenuSize
  37023. CheckItem
  37024. ClearMenuBar
  37025. CountMItems
  37026. DeleteMenu
  37027. DelMCEntries
  37028. DelMenuItem
  37029. DisableItem
  37030. DispMCInfo
  37031. DisposeMenu
  37032. DrawMenuBar
  37033. EnableItem
  37034. FlashMenuBar
  37035. getitem
  37036. GetItem
  37037. GetItemCmd
  37038. GetItemIcon
  37039. GetItemMark
  37040. GetItemStyle
  37041. GetMCEntry
  37042. GetMCInfo
  37043. GetMenu
  37044. GetMenuBar
  37045. GetMHandle
  37046. GetNewMBar
  37047. HiliteMenu
  37048. InitMenus
  37049. InitProcMenu
  37050. InsertMenu
  37051. InsertResMenu
  37052. InsMenuItem
  37053. insmenuitem
  37054. InvalidMenuBar
  37055. MenuChoice
  37056. MenuKey
  37057. MenuSelect
  37058. menuselect
  37059. newmenu
  37060. NewMenu
  37061. PopUpMenuSelect
  37062. setitem
  37063. SetItem
  37064. SetItemCmd
  37065. SetItemIcon
  37066. SetItemMark
  37067. SetItemStyle
  37068. SetMCEntries
  37069. SetMCInfo
  37070. SetMenuBar
  37071. SetMenuFlash
  37072.  
  37073. hierMenu
  37074. hMenuCmd
  37075. mCalcItemMsg
  37076. MCEntry
  37077. MCEntryPtr
  37078. mChooseMsg
  37079. mctAllItems
  37080. mctLastIDIndic
  37081. mDrawItemMsg
  37082. mDrawMsg
  37083. MenuCRsrc
  37084. MenuCRsrcHandle
  37085. MenuCRsrcPtr
  37086. MenuHandle
  37087. MenuInfo
  37088. MenuPtr
  37089. mPopUpMsg
  37090. mSizeMsg
  37091. noMark
  37092. textMenuProc
  37093.  
  37094. æKY noMark
  37095. æFc Menus.h
  37096. æT #define
  37097. æD #define noMark '\0' /*mark symbol for MarkItem*/
  37098. æC 
  37099.  
  37100. æKY mDrawMsg
  37101. æFc Menus.h
  37102. æT #define
  37103. æD 
  37104. /* menu defProc messages */
  37105.  
  37106. #define mDrawMsg 0
  37107. æC 
  37108. _______________________________________________________________________________
  37109.  
  37110. »The Menu Definition Procedure
  37111.  
  37112. The menu definition procedure is usually written in assembly language, but may be
  37113. written in any high-level language.
  37114.  
  37115. Assembly-language note:  The procedure’s entry point must be at the beginning.
  37116.  
  37117. You may choose any name you wish for the menu definition procedure. Here’s how you
  37118. would declare one named MyMenu:
  37119.  
  37120. PROCEDURE MyMenu (message:  INTEGER; theMenu:  MenuHandle; VAR menuRect:  Rect;
  37121.                   hitPt:  Point; VAR whichItem:  INTEGER);
  37122.  
  37123. The message parameter identifies the operation to be performed. It has one of the
  37124. following values:
  37125.  
  37126. #define mDrawMsg    0 /*draw the menu*/
  37127. #define mChooseMsg  1 /*tell which item was chosen and highlight it*/
  37128. #define mSizeMsg    2 /*calculate the menu's dimensions*/
  37129.  
  37130. The parameter theMenu indicates the menu that the operation will affect. MenuRect is
  37131. the rectangle (in global coordinates) in which the menu is located; it’s used when
  37132. the message is mDrawMsg or mChooseMsg.
  37133.  
  37134. Note:  MenuRect is declared as a VAR parameter not because its value is
  37135.        changed, but because of a Pascal feature that will cause an error
  37136.        when that parameter isn’t used.
  37137.  
  37138. The message mDrawMsg tells the menu definition procedure to draw the menu inside
  37139. menuRect. The current grafPort will be the Window Manager port. (For details on
  37140. drawing, see the QuickDraw chapter.) The standard menu definition procedure figures
  37141. out how to draw the menu items by looking in the menu record at the data that defines
  37142. them; this data is described in detail under “Formats of Resources for Menus” below.
  37143. For menus of your own definition, you may set up the data defining the menu items any
  37144. way you like, or even omit it altogether
  37145. (in which case all the information necessary to draw the menu would be in the menu
  37146. definition procedure itself). You should also check the enableFlags field of the menu
  37147. record to see whether the menu is disabled (or whether any of the menu items are
  37148. disabled, if you’re using all the flags), and if so, draw it in gray.
  37149.  
  37150. Note:  MenuKey will always search the menuData field of a MenuInfo record for
  37151.        Command-key equivalents until it finds a zero where a standard menu
  37152.        title should be, even if the MenuInfo record is for one of your own
  37153.        'MDEF' resources. To prevent MenuKey from finding a Command-key
  37154.        equivalent in your MenuInfo record, put a couple of bytes of zeros
  37155.        just after the menu’s title.
  37156.  
  37157. Warning:  Don’t change the font from the system font for menu text.
  37158.           (The Window Manager port uses the system font.)
  37159.  
  37160. When the menu definition procedure receives the message mChooseMsg, the hitPt parameter
  37161. is the mouse location (in global coordinates), and the whichItem parameter is the
  37162. item number of the last item that was chosen from this menu
  37163. (whichItem is initially set to 0). The procedure should determine whether the mouse
  37164. location is in an enabled menu item, by checking whether hitPt is inside menuRect,
  37165. whether the menu is enabled, and whether hitPt is in an enabled menu item:
  37166.  
  37167.   •  If the mouse location is in an enabled menu item, unhighlight whichItem
  37168.      and highlight the new item (unless the new item is the same as the
  37169.      whichItem), and return the item number of the new item in whichItem.
  37170.   •  If the mouse location isn’t in an enabled item, unhighlight whichItem
  37171.      and return 0.
  37172.  
  37173. Note:  When the Menu Manager needs to make a chosen menu item blink, it
  37174.        repeatedly calls the menu definition procedure with the message
  37175.        mChooseMsg, causing the item to be alternately highlighted and
  37176.        unhighlighted.
  37177.  
  37178. Finally, the message mSizeMsg tells the menu definition procedure to calculate the
  37179. horizontal and vertical dimensions of the menu and store them in the menuWidth and
  37180. menuHeight fields of the menu record.
  37181.  
  37182. The following section describes changes to the default menu definition procedure
  37183. ('MDEF' resource 0); some of the information presented in this section is accessible
  37184. only through assembly language.
  37185.  
  37186. Note:  These features will work with the 64K ROM if the new menu definition
  37187.        procedure is in the system resource file.
  37188.  
  37189. »Variable Size Fonts
  37190.  
  37191. Menus are displayed in the system font. Since the system font and font size can now
  37192. be changed, the menu definition procedure calls the QuickDraw procedure GetFontInfo
  37193. for the system font to determine the height of menu items
  37194.  
  37195. »Scrolling Menus
  37196.  
  37197. The default menu definition procedure allows longer menus by implementing automatic
  37198. scrolling. If the entire menu cannot be drawn on screen, dragging the cursor below
  37199. the last displayed item will cause the items in the menu to scroll up. Similarly, if
  37200. items have been scrolled past the top of the menu, dragging the cursor into the
  37201. highlighted portion of the menu bar will cause the menu to scroll back down. The
  37202. maximum number of items that can be drawn on the standard Macintosh screen with this
  37203. new menu definition function is 19 (instead of 20).
  37204.  
  37205. Warning:  You should not disable any menu items in a menu containing more than
  37206.           31 items because the enableFlags field of the MenuInfoRec can only
  37207.           handle 31 items.
  37208.  
  37209. æKY mChooseMsg
  37210. æFc Menus.h
  37211. æT #define
  37212. æD #define mChooseMsg 1
  37213. æC 
  37214.  
  37215. æKY mSizeMsg
  37216. æFc Menus.h
  37217. æT #define
  37218. æD #define mSizeMsg 2
  37219. æC 
  37220.  
  37221. æKY mDrawItemMsg
  37222. æFc Menus.h
  37223. æT #define
  37224. æD #define mDrawItemMsg 4
  37225. æC 
  37226.  
  37227. æKY mCalcItemMsg
  37228. æFc Menus.h
  37229. æT #define
  37230. æD #define mCalcItemMsg 5
  37231. æC 
  37232.  
  37233. æKY textMenuProc
  37234. æFc Menus.h
  37235. æT #define
  37236. æD #define textMenuProc 0
  37237. æC 
  37238.  
  37239. æKY hMenuCmd
  37240. æFc Menus.h
  37241. æT #define
  37242. æD #define hMenuCmd 27 /*itemCmd == 0x001B ==> hierarchical menu*/
  37243. æC 
  37244.  
  37245. æKY hierMenu
  37246. æFc Menus.h
  37247. æT #define
  37248. æD #define hierMenu -1 /*a hierarchical menu - for InsertMenu call*/
  37249. æC 
  37250.  
  37251. æKY mPopUpMsg
  37252. æFc Menus.h
  37253. æT #define
  37254. æD #define mPopUpMsg 3 /*menu defProc messages - place yourself*/
  37255. æC 
  37256.  
  37257. æKY mctAllItems
  37258. æFc Menus.h
  37259. æT #define
  37260. æD #define mctAllItems -98 /*search for all Items for the given ID*/
  37261. æC 
  37262.  
  37263. æKY mctLastIDIndic
  37264. æFc Menus.h
  37265. æT #define
  37266. æD #define mctLastIDIndic -99 /*last color table entry has this in ID field*/
  37267. æC 
  37268.  
  37269. æKY MenuInfo
  37270. MenuPtr
  37271. MenuHandle
  37272. æFc Menus.h
  37273. æT struct
  37274. æD struct MenuInfo {
  37275.     short menuID;
  37276.     short menuWidth;
  37277.     short menuHeight;
  37278.     Handle menuProc;
  37279.     long enableFlags;
  37280.     Str255 menuData;
  37281. };
  37282.  
  37283. typedef struct MenuInfo MenuInfo;
  37284. typedef MenuInfo *MenuPtr, **MenuHandle;
  37285.  
  37286. æC 
  37287. _______________________________________________________________________________
  37288.  
  37289. »MENU MANAGER DATA STRUCTURES
  37290. _______________________________________________________________________________
  37291.  
  37292. The Menu Manager keeps all the information it needs for its operations on a particular
  37293. menu in a menu record. The menu record contains the following:
  37294.  
  37295.   •  The menu ID, a number that identifies the menu. The menu ID can be the
  37296.      same number as the menu’s resource ID, though it doesn’t have to be.
  37297.   •  The menu title.
  37298.   •  The contents of the menu—the text and other parts of each item.
  37299.   •  The horizontal and vertical dimensions of the menu, in pixels. The menu
  37300.      items appear inside the rectangle formed by these dimensions; the black
  37301.      border and shadow of the menu appear outside that rectangle.
  37302.   •  A handle to the menu definition procedure.
  37303.   •  Flags telling whether each menu item is enabled or disabled, and whether
  37304.      the menu itself is enabled or disabled.
  37305.  
  37306. The data type for a menu record is called MenuInfo. A menu record is referred to by a
  37307. handle:
  37308.  
  37309. TYPE  MenuPtr    = ^MenuInfo;
  37310.       MenuHandle = ^MenuPtr;
  37311.  
  37312. You can store into and access all the necessary fields of a menu record with Menu
  37313. Manager routines, so normally you don’t have to know the exact field names. However,
  37314. if you want more information about the exact structure of a menu record—if you’re
  37315. defining your own menu types, for instance—it’s given below.
  37316.  
  37317. _______________________________________________________________________________
  37318.  
  37319. »The MenuInfo Data Type
  37320.  
  37321. The type MenuInfo is defined as follows:
  37322.  
  37323. TYPE  MenuInfo = RECORD
  37324.                    menuID:       INTEGER;  {menu ID}
  37325.                    menuWidth:    INTEGER;  {menu width in pixels}
  37326.                    menuHeight:   INTEGER;  {menu height in pixels}
  37327.                    menuProc:     Handle;   {menu definition procedure}
  37328.                    enableFlags:  LONGINT;  {tells if menu or items are enabled}
  37329.                    menuData:    Str255     {menu title (and other data)}
  37330.                  END;
  37331.  
  37332. The menuID field contains the menu ID. MenuWidth and menuHeight are the menu’s horizontal
  37333. and vertical dimensions in pixels. MenuProc is a handle to the menu definition procedure
  37334. for this type of menu.
  37335.  
  37336. Bit 0 of the enableFlags field is 1 if the menu is enabled, or 0 if it’s disabled.
  37337. Bits 1 to 31 similarly tell whether each item in the menu is enabled or disabled.
  37338.  
  37339. The menuData field contains the menu title followed by variable-length data that
  37340. defines the text and other parts of the menu items. The Str255 data type enables you
  37341. to access the title from Pascal; there’s actually additional data beyond the title
  37342. that’s inaccessible from Pascal and is not reflected in the MenuInfo data structure.
  37343.  
  37344. Warning:  You can read the menu title directly from the menuData field, but
  37345.           do not change the title directly, or the data defining the menu
  37346.           items may be destroyed.
  37347.  
  37348.  
  37349. The MenuInfo data structure is shown below; this version is similar to what is shown
  37350. earlier in this section, but includes additional information about menu items.
  37351.  
  37352. Warning:  The MenuInfo data structure is listed for information only;
  37353.           applications should never access it directly. This structure is
  37354.           not a valid Pascal type because of its dynamic size; it’s shown
  37355.           for conceptual purposes only.
  37356.  
  37357. TYPE  MenuInfo = RECORD
  37358.                    menuID:       INTEGER;  {menu ID}
  37359.                    menuWidth:    INTEGER;  {pixels}
  37360.                    menuHeight:   INTEGER;  {pixels}
  37361.                    menuProc:     Handle;   {handle}
  37362.                    enableFlags:  LONGINT;  {bit string}
  37363.                    menuTitle:    String;   {menu title name}
  37364.                    itemData:     ARRAY [1..X] OF
  37365.                                  itemString:  string;  {item name}
  37366.                                  itemIcon:    BYTE;    {iconnum-256}
  37367.                                  itemCmd:     char;    {item cmd key}
  37368.                                  itemMark:    char;    {item mark is a byte}
  37369.                                                        { value for }
  37370.                                                        { hierachical menus}
  37371.                                  itemStyle:   Style;   {bit string}
  37372.                    endMarker:    Byte;                 {zero-length string }
  37373.                                                        { indicates no more }
  37374.                                                        { menu items}
  37375.                  END;
  37376.  
  37377. Field descriptions
  37378.  
  37379. menuID       The menuID field contains the menu ID of the menu.
  37380. menuWidth    The menuWidth field contains the width in pixels of the menu.
  37381. menuHeight   The menuHeight field contains the height in pixels of the menu.
  37382. menuProc     The menuProc field contains a handle to the menu’s definition
  37383.              procedure.
  37384. enableFlags  The enableFlags field is a bit string which allows the menu and
  37385.              the first 31 items to be enabled or disabled. All items beyond
  37386.              31 are always enabled.
  37387. menuTitle    The menuTitle field is a string containing the menu title.
  37388. itemData     The itemData field is an array containing the following
  37389.              information for each menu item: item name, item icon number,
  37390.              item command key equivalent, item mark, and  item style. For
  37391.              hierarchical menus, the itemMark field is a byte value.
  37392. endMarker    The endMarker field is a byte value, which contains zero if
  37393.              there are no more menu items.
  37394.  
  37395. The contents of the itemData array are the same for hierarchical and nonhierarchical
  37396. menus, but for hierarchical menus the itemMark field is a byte value, which limits
  37397. hierarchical menu menuID values to between 0 and 255. Hierarchical menus numbered 236
  37398. to 255 are reserved for use by desk accessories. Desk accessories must remove their
  37399. hierarchical menus from the MenuList each time their window is not the frontmost, to
  37400. prevent hierarchical menu collisions with other desk accessories.
  37401.  
  37402. æKY MCEntry
  37403. MCEntryPtr
  37404. æFc Menus.h
  37405. æT struct
  37406. æD struct MCEntry {
  37407.     short mctID; /*menu ID.  ID = 0 is the menu bar*/
  37408.     short mctItem; /*menu Item. Item = 0 is a title*/
  37409.     RGBColor mctRGB1; /*usage depends on ID and Item*/
  37410.     RGBColor mctRGB2; /*usage depends on ID and Item*/
  37411.     RGBColor mctRGB3; /*usage depends on ID and Item*/
  37412.     RGBColor mctRGB4; /*usage depends on ID and Item*/
  37413.     short mctReserved; /*reserved for internal use*/
  37414. };
  37415.  
  37416. typedef struct MCEntry MCEntry;
  37417. typedef MCEntry *MCEntryPtr;
  37418.  
  37419. typedef MCEntry MCTable[1], *MCTablePtr, **MCTableHandle;
  37420.  
  37421. æC 
  37422. »Color Menu Data Structures
  37423.  
  37424. For the Macintosh II, menus can be colored in 2-bit mode or higher, in both color and
  37425. gray-scale. The menu color information is contained in a table format, but because
  37426. this format is different from the standard color table format, it is referred to as
  37427. the menu color information table, rather than the menu color table.  A menu color
  37428. information table is composed of several entries, each of  which is an MCEntry record.
  37429. These data structures are shown below:
  37430.  
  37431. TYPE  MCEntryPtr = ^MCEntry;
  37432.       MCEntry    = RECORD
  37433.                      mctID:        INTEGER;   {menu ID. ID = 0 is }
  37434.                                               { the menu bar}
  37435.                      mctItem:      INTEGER;   {menu entry. Item = 0 }
  37436.                                               { is a title}
  37437.                      mctRGB1:      RGBColor;  {usage depends on ID and Item}
  37438.                      mctRGB2:      RGBColor;  {usage depends on ID and Item}
  37439.                      mctRGB3:      RGBColor;  {usage depends on ID and Item}
  37440.                      mctRGB4:      RGBColor;  {usage depends on ID and Item}
  37441.                      mctReserved:  INTEGER;   {reserved for internal use}
  37442.                    END;
  37443.  
  37444.       MCTable       = ARRAY [0..0] of MCEntry;  {The menu entries are }
  37445.                                                 { represented in this array}
  37446.       MCTablePtr    = ^MCTable;
  37447.       MCTableHandle = ^MCTablePtr;
  37448.  
  37449. Field descriptions
  37450.  
  37451. mctID        The mctID field contains the menu ID of  the menu. A value of
  37452.              mctID = 0 means that this is the menu bar.
  37453. mctItem      The mctItem field contains the menu item. A value of item = 0
  37454.              means that the item is a menu title.
  37455. mctRGB1      The mctRGB1 field contains a color value which depends on the
  37456.              mctID and mctItem. See the description in the following section.
  37457. mctRGB2      The mctRGB2 field contains a color value which depends on the
  37458.              mctID and mctItem. See the description in the following section.
  37459. mctRGB3      The mctRGB3 field contains a color value which depends on the
  37460.              mctID and mctItem. See the description in the following section.
  37461. mctRGB4      The mctRGB4 field contains a color value which depends on the
  37462.              mctID and mctItem. See the description in the following section.
  37463. mctReserved  The mctReserved field is used internally; applications must not
  37464.              use this field.
  37465.  
  37466. The color information table is created at InitMenus time, and its handle is stored in
  37467. the global variable MenuCInfo ($D50). Like the MenuList data structure, it is only
  37468. created the first time InitMenus or InitProcMenu is called for an application.
  37469.  
  37470. A menu color information table is shown in Figure 3.
  37471.  
  37472. •••Refer to Figure 3.•••
  37473.  
  37474. Figure 3–Menu Color Information Table
  37475.  
  37476. There is always at least one entry in the color table, the last entry, which has the
  37477. arbitrary value –99 in the ID field as an “end-of-table” marker. (This means that the
  37478. value –99 cannot be used as an ID by an application.) Note that the other fields in
  37479. the “end-of-table” entry are reserved by use for Apple.  Each entry in the color
  37480. information table has seven fields.
  37481.  
  37482. The first two fields define the entry’s menu and item. The last field is used internally
  37483. and has no information for use by programmers. The other fields define colors depending
  37484. on what type of menu element the entry describes. All colors are specified as RGB
  37485. colors. There are three types of entries in the menu color information table: one
  37486. type for the menu bar, one type for menu titles, and one type for menu items.
  37487.  
  37488. The menu bar entry has ID = 0, Item = 0. There will be at most one menu bar entry in
  37489. the color information table. If there is no menu bar entry, the default menu bar
  37490. colors are black text on a white background. The fields in a menu bar entry are as
  37491. follows:
  37492.  
  37493.   •  mctRGB1 is the default color for menu titles. If a menu title doesn’t
  37494.      have an entry in the table, then this is the color used to draw the title.
  37495.   •  mctRGB2 is the default color for the background of a pulled down menu.
  37496.      If a menu title doesn’t have an entry in the table, this color is used
  37497.      as the menu’s background color.
  37498.   •  mctRGB3 is the default color for the items in a pulled down menu. If a
  37499.      menu item doesn’t have an entry in a table, and if the title for that
  37500.      menu item doesn’t also have an entry, this color will be used to color
  37501.      the mark, name, and Command-key equivalent of the item.
  37502.   •  mctRGB4 is the menu bar color.
  37503.  
  37504. The menu title entry has ID <> 0, Item = 0. There will be at most one title entry for
  37505. each menu in the color information table. If there is no title entry, the title, menu
  37506. background, and menu items are drawn using the defaults found in the menu bar entry.
  37507. If there is no menu bar entry, the default colors are black on white. The fields in a
  37508. title entry areas follows:
  37509.  
  37510.   •  mctRGBG1 is the title color.
  37511.   •  mctRGB2 is the menu bar color. This is duplicated here from the menu bar
  37512.      entry to speed menu drawing.
  37513.   •  mctRGB3 is the default color for the menu items. If a menu item doesn’t
  37514.      have an entry in the table, this color will be used to color the mark,
  37515.      name, and Command-key equivalent of the item.
  37516.   •  mctRGB4 is the menu’s background color.
  37517.  
  37518. The menu item entry has ID <> 0, Item <> 0. There will be at most one item entry for
  37519. each menu item in the color information table. If there is no entry for a particular
  37520. item, the item mark, name, and Command-key equivalent are drawn using the defaults
  37521. found in the title entry. If there is no title entry, the information in the menu bar
  37522. entry is used. If there is no menu bar entry, the mark, name, and Command-key equivalent
  37523. are drawn in black. The fields in an item entry are as follows:
  37524.  
  37525.   •  mctRGB1 is the mark color.
  37526.   •  mctRGB2 is the name color.
  37527.   •  mctRGB3 is the Command-key equivalent.
  37528.   •  mctRGB4 is the menu’s background color. It’s duplicated here to
  37529.      speed menu drawing.
  37530.  
  37531. It’s not possible to specify an icon’s color. Black and white icons are drawn in the
  37532. item’s name color. Icons may be colored using a 'cicn' resource instead of an 'ICON'
  37533. resource. When an icon is drawn in a menu, the menu defproc attempts to load the
  37534. 'cicn' resource first, and if it isn’t found, searches for the 'ICON' resource. See
  37535. the QuickDraw chapter for more information on color icons.
  37536. _______________________________________________________________________________
  37537.  
  37538. »Menu Color Information Table Resource Format
  37539.  
  37540. The resource type for a menu color information table is 'mctb'. Once read into memory,
  37541. this data is transferred into the application’s menu color information table. The
  37542. resource data format is identical to an MCTable, with the addition of a leading word
  37543. that contains the number of entries in the resource:
  37544.  
  37545. TYPE  MenuCRsrc =  RECORD
  37546.                      numEntries:  integer;
  37547.                      data:        array [1..numEntries] of MCEntry;
  37548.                    END;
  37549.  
  37550. The 'mctb' resource is loaded automatically by two routines. InitMenus attempts to
  37551. load an 'mctb' resource = 0, and if it is successful, adds the colors to the application’s
  37552. menu color information table. GetMenu attempts to load an 'mctb' resource with the
  37553. same resource ID as the menu it has loaded, and if it succeeds, it adds the colors to
  37554. the application’s menu color information table.
  37555.  
  37556. æKY MenuCRsrc
  37557. MenuCRsrcPtr
  37558. MenuCRsrcHandle
  37559. æFc Menus.h
  37560. æT struct
  37561. æD struct MenuCRsrc {
  37562.     short numEntries; /*number of entries*/
  37563.     MCEntry data[1]; /*ARRAY [1..numEntries] of MCEntry*/
  37564. };
  37565.  
  37566. typedef struct MenuCRsrc MenuCRsrc;
  37567. typedef MenuCRsrc *MenuCRsrcPtr, **MenuCRsrcHandle;
  37568.  
  37569. æC 
  37570.  
  37571. æKY InitMenus
  37572. æFc Menus.h
  37573. æT Function
  37574. æTN A930
  37575. æD pascal void InitMenus(void)
  37576.     = 0xA930; 
  37577. æDT InitMenus()(void);
  37578. æMM
  37579. æRT 211
  37580. æRI I-351, V-242, P-101, 107, 175
  37581. æC 
  37582. InitMenus initializes the Menu Manager. It allocates space for the menu list (a
  37583. relocatable block in the heap large enough for the maximum-size menu list), and draws
  37584. the (empty) menu bar. Call InitMenus once before all other Menu Manager routines. An
  37585. application should never have to call this procedure more than once; to start afresh
  37586. with all new menus, use ClearMenuBar.
  37587.  
  37588. Note:  The Window Manager initialization procedure InitWindows has already
  37589.        drawn the empty menu bar; InitMenus redraws it.
  37590.  
  37591. The InitMenus routine now allocates a dynamic MenuList structure with no menus or
  37592. hierarchical menus. After allocating the initial MenuList, it attempts to load an
  37593. 'mctb' resource = 0. If the user has chosen default menu color values, this 'mctb'
  37594. resource = 0 will exist in the System file. If the 'mctb' is loaded, the information
  37595. contained in the resource is added to the menu color information table by making a
  37596. call to SetMCEntries. If there is an 'mctb' resource = 0 among the application’s
  37597. resources, this will be loaded instead of the default 'mctb' in the System file.
  37598.  
  37599. æKY NewMenu
  37600. æFc Menus.h
  37601. æT Function
  37602. æTN A931
  37603. æD pascal MenuHandle NewMenu(short menuID,const Str255 menuTitle)
  37604.     = 0xA931; 
  37605. æDT MenuHandle myVariable = NewMenu((short) menuID,(const Str255) menuTitle);
  37606. æMM
  37607. æRI I-351, P-102, 103
  37608. æC 
  37609. NewMenu allocates space for a new menu with the given menu ID and title, and returns
  37610. a handle to it. It sets up the menu to use the standard menu definition procedure.
  37611. (The menu definition procedure is read into memory if it isn’t already in memory.)
  37612. The new menu (which is created empty) is not installed in the menu list. To use this
  37613. menu, you must first call AppendMenu or AddResMenu to fill it with items, InsertMenu
  37614. to place it in the menu list, and DrawMenuBar to update the menu bar to include the
  37615. new title.
  37616.  
  37617. Application menus should always have positive menu IDs. Negative menu IDs are reserved
  37618. for menus belonging to desk accessories. No menu should ever have a menu ID of 0.
  37619.  
  37620. If you want to set up the title of the Apple menu from your program instead of reading
  37621. it in from a resource file, you can use the constant appleMark (defined by the Font
  37622. Manager as the character code for the apple symbol). For example, you can declare the
  37623. string variable
  37624.  
  37625.   VAR myTitle:  STRING[1];
  37626.  
  37627. and do the following:
  37628.  
  37629.   myTitle := ' ';
  37630.   myTitle[1] := CHR(appleMark)
  37631.  
  37632. To release the memory occupied by a menu that you created with NewMenu, call DisposeMenu.
  37633.  
  37634. æKY GetMenu
  37635. æFc Menus.h
  37636. æT Function
  37637. æTN A9BF
  37638. æD pascal MenuHandle GetMenu(short resourceID)
  37639.     = 0xA9BF; 
  37640. æDT MenuHandle myVariable = GetMenu((short) resourceID);
  37641. æMM
  37642. æRT 78
  37643. æRI I-351, V-243, N78-2, P-102, 172
  37644. æC 
  37645. Assembly-language note:  The macro you invoke to call GetMenu from
  37646.                          assembly language is named _GetRMenu.
  37647.  
  37648. GetMenu returns a menu handle for the menu having the given resource ID. It calls the
  37649. Resource Manager to read the menu from the resource file into a menu record in memory.
  37650. GetMenu stores the handle to the menu definition procedure in the menu record, reading
  37651. the procedure from the resource file into memory if necessary. If the menu or the
  37652. menu definition procedure can’t be read from the resource file, GetMenu returns NIL.
  37653. To use the menu, you must call InsertMenu to place it in the menu list and DrawMenuBar
  37654. to update the menu bar to include the new title.
  37655.  
  37656. Warning:  Call GetMenu only once for a particular menu. If you need the menu
  37657.           handle to a menu that’s already in memory, use the Resource Manager
  37658.           function GetResource.
  37659.  
  37660. To release the memory occupied by a menu that you read from a resource file with
  37661. GetMenu, use the Resource Manager procedure ReleaseResource.
  37662.  
  37663. After loading a 'MENU' resource, GetMenu attempts to load an 'mctb' resource with the
  37664. same resource ID. If an 'mctb' is loaded, all of the entries are added to the application’s
  37665. menu color information table by making a call to SetMCEntries.
  37666.  
  37667. æKY DisposeMenu
  37668. æFc Menus.h
  37669. æT Function
  37670. æTN A932
  37671. æD pascal void DisposeMenu(MenuHandle theMenu)
  37672.     = 0xA932; 
  37673. æDT DisposeMenu((MenuHandle) theMenu);
  37674. æMM
  37675. æRI I-352, P-103, 168
  37676. æC  
  37677. Assembly-language note:  The macro you invoke to call DisposeMenu from
  37678.                          assembly language is named _DisposMenu.
  37679.  
  37680. Call DisposeMenu to release the memory occupied by a menu that you allocated with
  37681. NewMenu. (For menus read from a resource file with GetMenu, use the Resource Manager
  37682. procedure ReleaseResource instead.) This is useful if you’ve created temporary menus
  37683. that you no longer need.
  37684.  
  37685. Warning:  Make sure you remove the menu from the menu list (with DeleteMenu)
  37686.           before disposing of it.
  37687.  
  37688. æKY AppendMenu
  37689. æFc Menus.h
  37690. æT Function
  37691. æTN A933
  37692. æD pascal void AppendMenu(MenuHandle menu,const Str255 data)
  37693.     = 0xA933; 
  37694. æDT AppendMenu((MenuHandle) menu,(const Str255) data);
  37695. æMM
  37696. æRI I-352, V-243, P-102
  37697. æC  
  37698. AppendMenu adds an item or items to the end of the given menu, which must previously
  37699. have been allocated by NewMenu or read from a resource file by GetMenu. The data
  37700. string consists of the text of the menu item; it may be blank but should not be the
  37701. empty string. If it begins with a hyphen (–), the item will be a dividing line across
  37702. the width of the menu. As described in the section “Creating a Menu in Your Program”,
  37703. the following meta-characters may be embedded in the data string:
  37704.  
  37705.   Meta-character    Usage
  37706.  
  37707.   ; or Return       Separates multiple items
  37708.   ^                 Followed by an icon number, adds that icon to the item
  37709.   !                 Followed by a character, marks the item with that character
  37710.   <                 Followed by B, I, U, O, or S, sets the character style
  37711.                     of the item
  37712.   /                 Followed by a character, associates a keyboard equivalent
  37713.                     with the item
  37714.   (                 Disables the item
  37715.  
  37716. Once items have been appended to a menu, they cannot be removed or rearranged. AppendMenu
  37717. works properly whether or not the menu is in the menu list.
  37718.  
  37719. _______________________________________________________________________________
  37720.  
  37721. »CREATING A MENU IN YOUR PROGRAM
  37722. _______________________________________________________________________________
  37723.  
  37724. The best way to create your application’s menus is to set them up as resources and
  37725. read them in from a resource file. If you want your application to create the menus
  37726. itself, though, it must call the NewMenu and AppendMenu routines. NewMenu creates a
  37727. new menu data structure, returning a handle to it. AppendMenu takes a string and a
  37728. handle to a menu and adds the items in the string to the end of the menu.
  37729.  
  37730. The string passed to AppendMenu consists mainly of the text of the menu items. For a
  37731. dividing line, use one hyphen (–); AppendMenu ignores any following characters, and
  37732. draws a dotted line across the width of the menu. For a blank item, use one or more
  37733. spaces. Other characters interspersed in the string have special meaning to the Menu
  37734. Manager. These “meta-characters” are used in conjunction with text to separate menu
  37735. items or alter their appearance (for example, you can use one to disable any dividing
  37736. line or blank item). The
  37737. meta-characters aren’t displayed in the menu.
  37738.  
  37739.   Meta-character    Meaning
  37740.  
  37741.   ; or Return       Separates items
  37742.   ^                 Item has an icon
  37743.   !                 Item has a check or other mark
  37744.   <                 Item has a special character style
  37745.   /                 Item has a keyboard equivalent
  37746.   (                 Item is disabled
  37747.  
  37748. None, any, or all of these meta-characters can appear in the AppendMenu string;
  37749. they’re described in detail below. To add one text-only item to a menu would require
  37750. a simple string without any meta-characters:
  37751.  
  37752.   AppendMenu(thisMenu,'Just Enough')
  37753.  
  37754. An extreme example could use many meta-characters:
  37755.  
  37756.   AppendMenu(thisMenu,'(Too Much^1<B/T')
  37757.  
  37758. This example adds to the menu an item whose text is “Too Much”, which is disabled,
  37759. has icon number 1, is boldfaced, and can be invoked by Command-T. Your menu items
  37760. should be much simpler than this.
  37761.  
  37762. Note:  If you want any of the meta-characters to appear in the text of a
  37763.        menu item, you can include them by changing the text with the Menu
  37764.        Manager procedure SetItem.
  37765.  
  37766. _______________________________________________________________________________
  37767.  
  37768. »Multiple Items
  37769.  
  37770. Each call to AppendMenu can add one or many items to the menu. To add multiple items
  37771. in the same call, use a semicolon (;) or a Return character to separate the items.
  37772. The call
  37773.  
  37774.   AppendMenu(thisMenu,'Cut;Copy')
  37775.  
  37776. has exactly the same effect as the calls
  37777.  
  37778.   AppendMenu(thisMenu,'Cut');
  37779.   AppendMenu(thisMenu,'Copy')
  37780.  
  37781. _______________________________________________________________________________
  37782.  
  37783. »Items with Icons
  37784.  
  37785. A circumflex (^ ) followed by a digit from 1 to 9 indicates that an icon should
  37786. appear to the left of the text in the menu. The digit, called the icon number, yields
  37787. the resource ID of the icon in the resource file. Icon resource IDs 257 through 511
  37788. are reserved for menu icons; thus the Menu Manager adds 256 to the icon number to get
  37789. the proper resource ID.
  37790.  
  37791. Note:  The Menu Manager gets the icon number by subtracting 48 from the ASCII
  37792.        code of the character following the “^” (since, for example, the ASCII
  37793.        code of “1” is 49). You can actually follow the “^” with any character
  37794.        that has an ASCII code greater than 48.
  37795.  
  37796. You can also use the SetItemIcon procedure to install icons in a menu; it accepts any
  37797. icon number from 1 to 255.
  37798.  
  37799. _______________________________________________________________________________
  37800.  
  37801. »Marked Items
  37802.  
  37803. You can use an exclamation point (!) to cause a check mark or any other character to
  37804. be placed to the left of the text (or icon, if any). Follow the exclamation point
  37805. with the character of your choice; note, however, that normally you can’t type a
  37806. check mark from the keyboard. To specify a check mark, you need to take special
  37807. measures:  Declare a string variable to have the length of the desired AppendMenu
  37808. string, and assign it that string with a space following the exclamation point. Then
  37809. separately store the check mark in the position of the space.
  37810.  
  37811. For example, suppose you want to use AppendMenu to specify a menu item that has the
  37812. text “Word Wraparound” (15 characters) and a check mark to its left. You can declare
  37813. the string variable
  37814.  
  37815.   VAR s:  STRING[17];
  37816.  
  37817. and do the following:
  37818.  
  37819.   s := '! Word Wraparound';
  37820.   s[2] := CHR(checkMark);
  37821.   AppendMenu(thisMenu,s)
  37822.  
  37823. The constant checkMark is defined by the Font Manager as the character code for the
  37824. check mark.
  37825.  
  37826. Note:  The Font Manager also defines constants for certain other special
  37827.        characters that can’t normally be typed from the keyboard:  the apple
  37828.        symbol, the Command key symbol, and a diamond symbol. These symbols
  37829.        can be specified in the same way as the check mark.
  37830.  
  37831. You can call the SetItemMark or CheckItem procedures to change or clear the mark, and
  37832. the GetItemMark procedure to find out what mark, if any, is being used.
  37833.  
  37834. _______________________________________________________________________________
  37835.  
  37836. »Character Style of Items
  37837.  
  37838. The system font is the only font available for menus; however, you can vary the
  37839. character style of menu items for clarity and distinction. The meta-character for
  37840. specifying the character style of an item’s text is the less-than symbol
  37841. (<). With AppendMenu, you can assign one and only one of the stylistic variations
  37842. listed below.
  37843.  
  37844.   <B    Bold
  37845.   <I    Italic
  37846.   <U    Underline
  37847.   <O    Outline
  37848.   <S    Shadow
  37849.  
  37850. The SetItemStyle procedure allows you to assign any combination of stylistic variations
  37851. to an item. For a further discussion of character style, see the QuickDraw chapter.
  37852.  
  37853. _______________________________________________________________________________
  37854.  
  37855. »Items with Keyboard Equivalents
  37856.  
  37857. A slash (/) followed by a character associates that character with the item, allowing
  37858. the item to be invoked from the keyboard with the Command key. The specified character
  37859. (preceded by the Command key symbol) appears at the right of the item’s text in the
  37860. menu.
  37861.  
  37862. Note:  Remember to specify the character in uppercase if it’s a letter, and
  37863.        not to specify other shifted characters or numbers.
  37864.  
  37865. Given a keyboard equivalent typed by the user, you call the MenuKey function to find
  37866. out which menu item was invoked.
  37867.  
  37868. _______________________________________________________________________________
  37869.  
  37870. »Disabled Items
  37871.  
  37872. The meta-character that disables an item is the left parenthesis, “(”. A disabled
  37873. item cannot be chosen; it appears dimmed in the menu and is not highlighted when the
  37874. cursor moves over it.
  37875.  
  37876. Menu items that are used to separate groups of items (such as a line or a blank item)
  37877. should always be disabled. For example, the call
  37878.  
  37879.   AppendMenu(thisMenu,'Undo;(-;Cut')
  37880.  
  37881. adds two enabled menu items, Undo and Cut, with a disabled item consisting of a line
  37882. between them.
  37883.  
  37884. You can change the enabled or disabled state of a menu item with the DisableItem and
  37885. EnableItem procedures.
  37886.  
  37887. æKY AddResMenu
  37888. æFc Menus.h
  37889. æT Function
  37890. æTN A94D
  37891. æD pascal void AddResMenu(MenuHandle theMenu,ResType theType)
  37892.     = 0xA94D; 
  37893. æDT AddResMenu((MenuHandle) theMenu,(ResType) theType);
  37894. æMM
  37895. æRT 191, 198 
  37896. æRI I-353, V-243, P-102
  37897. æC  
  37898. AddResMenu searches all open resource files for resources of type theType and appends
  37899. the names of all resources it finds to the given menu. Each resource name appears in
  37900. the menu as an enabled item, without an icon or mark, and in the plain character
  37901. style. The standard Menu Manager calls can be used to get the name or change its
  37902. appearance, as described in the section “Controlling the Appearance of Items”.
  37903.  
  37904. Note:  If the name of your desk accessory appears not to have been sorted
  37905.        and is inserted at the end of the Apple menu, the name is missing
  37906.        the leading null character.
  37907.  
  37908. Note:  So that you can have resources of the given type that won’t appear in
  37909.        the menu, any resource names that begin with a period (.) or a percent
  37910.        sign (%) aren’t appended by AddResMenu.
  37911.  
  37912. Use this procedure to fill a menu with the names of all available fonts or desk
  37913. accessories. For example, if you declare a variable as
  37914.  
  37915.   VAR fontMenu:  MenuHandle;
  37916.  
  37917. you can set up a menu containing all font names as follows:
  37918.  
  37919.   fontMenu := NewMenu(5,'Fonts');
  37920.   AddResMenu(fontMenu,'FONT')
  37921.  
  37922. Warning:  Before returning, AddResMenu issues the Resource Manager call
  37923.           SetResLoad(TRUE). If your program previously called SetResLoad(FALSE)
  37924.           and you still want that to be in effect after calling AddResMenu,
  37925.           you’ll have to call it again.
  37926.  
  37927. When AddResMenu or InsertResMenu is called for 'FONT' or 'FOND' resources, special
  37928. processing occurs for fontNumbers greater than or equal to $4000, as is the case for
  37929. international fonts. If the script associated with the font is currently active, then
  37930. the ItemCmd and ItemIcon fields are used to store information allowing the font names
  37931. to be displayed in the correct script.
  37932.  
  37933. There is a known problem with the AddResMenu and InsertResMenu routines, and with the
  37934. menu enable flags, when the number of items is greater than 31. Applications should
  37935. explicitly reenable or redisable all items after calling AddResMenu or InsertResMenu.
  37936. This is because only the first 31 items are affected by the enable flags: all items
  37937. 32 and greater are always enabled.
  37938.  
  37939. æKY InsertResMenu
  37940. æFc Menus.h
  37941. æT Function
  37942. æTN A951
  37943. æD pascal void InsertResMenu(MenuHandle theMenu,ResType theType,short afterItem)
  37944.     = 0xA951; 
  37945. æDT InsertResMenu((MenuHandle) theMenu,(ResType) theType,(short) afterItem);
  37946. æMM
  37947. æRI I-353, V-243
  37948. æC 
  37949. InsertResMenu is the same as AddResMenu (above) except that it inserts the resource
  37950. names in the menu where specified by the afterItem parameter:  If afterItem is 0, the
  37951. names are inserted before the first menu item; if it’s the item number of an item in
  37952. the menu, they’re inserted after that item; if it’s equal to or greater than the last
  37953. item number, they’re appended to the menu.
  37954.  
  37955. Note:  InsertResMenu inserts the names in the reverse of the order that
  37956.        AddResMenu appends them. For consistency between applications in
  37957.        the appearance of menus, use AddResMenu instead of InsertResMenu if
  37958.        possible.
  37959.  
  37960. æKY InsertMenu
  37961. æFc Menus.h
  37962. æT Function
  37963. æTN A935
  37964. æD pascal void InsertMenu(MenuHandle theMenu,short beforeID)
  37965.     = 0xA935; 
  37966. æDT InsertMenu((MenuHandle) theMenu,(short) beforeID);
  37967. æMM
  37968. æRI I-353, V-244, P-98, 102, 104, 175
  37969. æC 
  37970. InsertMenu inserts a menu into the menu list before the menu whose menu ID equals
  37971. beforeID. If beforeID is 0 (or isn’t the ID of any menu in the menu
  37972. list), the new menu is added after all others. If the menu is already in the menu
  37973. list or the menu list is already full, InsertMenu does nothing. Be sure to call
  37974. DrawMenuBar to update the menu bar.
  37975.  
  37976. The InsertMenu routine can be used to add a hierarchical menu to the Menulist. If
  37977. beforeID is equal to –1, the menu is a hierarchical menu. If beforeID is greater than
  37978. or equal to zero, the menu is a nonhierarchical menu.
  37979.  
  37980. It isn’t necessary for every menu in the hierarchical menu portion of the MenuList to
  37981. be currently in use; that is, attached to a menu item. Hierarchical menus that are
  37982. currently unused, but may be used some time later by the application, may be stored
  37983. there, and attached to menu items only as needed. You should realize that this can
  37984. cause problems if the unattached submenus have items with Command-key equivalents,
  37985. because MenuKey will find these equivalents even though the menu is unattached.
  37986.  
  37987. æKY DrawMenuBar
  37988. æFc Menus.h
  37989. æT Function
  37990. æTN A937
  37991. æD pascal void DrawMenuBar(void)
  37992.     = 0xA937; 
  37993. æDT DrawMenuBar()(void);
  37994. æMM
  37995. æRI I-354, V-244, P-101, 104, 169
  37996. æC 
  37997. DrawMenuBar redraws the menu bar according to the menu list, incorporating any changes
  37998. since the last call to DrawMenuBar. This procedure should always be called after a
  37999. sequence of InsertMenu or DeleteMenu calls, and after ClearMenuBar, SetMenuBar, or
  38000. any other routine that changes the menu list.
  38001.  
  38002. DrawMenuBar now properly highlights the selected menu title, if there is one. If your
  38003. application program assumed that DrawMenuBar would redraw the menu incorrectly, and
  38004. called HiliteMenu or FlashMenuBar to compensate, what happens now is that the menu
  38005. bar is redrawn properly, and the next call to HiliteMenu or FlashMenuBar causes the
  38006. highlighted title to become unhighlighted.
  38007.  
  38008. æKY InvalidMenuBar
  38009. æFc Menus.h
  38010. æT Function
  38011. æTN A81D
  38012. æD 
  38013. union AliasInfoType InvalidMenuBar(void)
  38014.     = 0xA81D; 
  38015. æDT union AliasInfoType myVariable = InvalidMenuBar()(void);
  38016. æC 
  38017.  
  38018. æKY DeleteMenu
  38019. æFc Menus.h
  38020. æT Function
  38021. æTN A936
  38022. æD pascal void DeleteMenu(short menuID)
  38023.     = 0xA936; 
  38024. æDT DeleteMenu((short) menuID);
  38025. æRI I-354, V-244, P-103, 104, 167
  38026. æC 
  38027. DeleteMenu deletes a menu from the menu list. If there’s no menu with the given menu
  38028. ID in the menu list, DeleteMenu has no effect. Be sure to call DrawMenuBar to update
  38029. the menu bar; the menu titles following the deleted menu will move over to fill the
  38030. vacancy.
  38031.  
  38032. Note:  DeleteMenu simply removes the menu from the list of currently available
  38033.        menus; it doesn’t release the memory occupied by the menu data structure.
  38034.  
  38035. The DeleteMenu routine removes all color entries from the menu color information
  38036. table for the specified menuID. It first checks the hierarchical portion of the
  38037. MenuList for the menuID and, if it finds it, deletes the menu; it then returns. If
  38038. the menu is not found in the hierarchical portion of the MenuList, the regular portion
  38039. is checked.
  38040.  
  38041. The hierarchical portion of the MenuList is always checked first, so that any desk
  38042. accessories whose hierarchical menu IDs conflict with an application’s regular menu
  38043. IDs can call DeleteMenu without deleting the application’s menus.
  38044.  
  38045. æKY ClearMenuBar
  38046. æFc Menus.h
  38047. æT Function
  38048. æTN A934
  38049. æD pascal void ClearMenuBar(void)
  38050.     = 0xA934; 
  38051. æDT ClearMenuBar()(void);
  38052. æRI I-354, V-247
  38053. æC 
  38054. Call ClearMenuBar to remove all menus from the menu list when you want to start
  38055. afresh with all new menus. Be sure to call DrawMenuBar to update the menu bar.
  38056.  
  38057. Note:  ClearMenuBar, like DeleteMenu, doesn’t release the memory occupied by
  38058.        the menu data structures; it merely removes them from the menu list.
  38059.  
  38060. You don’t have to call ClearMenuBar at the beginning of your program, because InitMenus
  38061. clears the menu list for you.
  38062.  
  38063. ClearMenuBar clears both the MenuList and the application’s menu color information
  38064. table.
  38065.  
  38066. æKY GetNewMBar
  38067. æFc Menus.h
  38068. æT Function
  38069. æTN A9C0
  38070. æD pascal Handle GetNewMBar(short menuBarID)
  38071.     = 0xA9C0; 
  38072. æDT Handle myVariable = GetNewMBar((short) menuBarID);
  38073. æMM
  38074. æRI I-354, V-247, P-102, 172
  38075. æC 
  38076. GetNewMBar creates a menu list as defined by the menu bar resource having the given
  38077. resource ID, and returns a handle to it. If the resource isn’t already in memory,
  38078. GetNewMBar reads it into memory from the resource file. If the resource can’t be
  38079. read, GetNewMBar returns NIL. GetNewMBar calls GetMenu to get each of the individual
  38080. menus.
  38081.  
  38082. To make the menu list created by GetNewMBar the current menu list, call SetMenuBar.
  38083. To release the memory occupied by the menu list, use the Memory Manager procedure
  38084. DisposHandle.
  38085.  
  38086. Warning:  You don’t have to know the individual menu IDs to use GetNewMBar,
  38087.           but that doesn’t mean you don’t have to know them at all:  To do
  38088.           anything further with a particular menu, you have to know its ID
  38089.           or its handle (which you can get by passing the ID to GetMHandle,
  38090.           as described in the section “Miscellaneous Routines”).
  38091.  
  38092. GetNewMBar begins by calling ClearMenuBar, which clears both the MenuList and the
  38093. application’s menu color information table. Before returning the Handle to the new
  38094. MenuList, it restores the previous MenuList. It doesn’t restore the previous menu
  38095. color information table. If that is desired, the application must use GetMCInfo
  38096. before calling GetNewMBar, and call SetMCInfo afterwards.
  38097.  
  38098. æKY GetMenuBar
  38099. æFc Menus.h
  38100. æT Function
  38101. æTN A93B
  38102. æD pascal Handle GetMenuBar(void)
  38103.     = 0xA93B; 
  38104. æDT Handle myVariable = GetMenuBar()(void);
  38105. æMM
  38106. æRI I-355, P-172
  38107. æC 
  38108. GetMenuBar creates a copy of the current menu list and returns a handle to the copy.
  38109. You can then add or remove menus from the menu list (with InsertMenu, DeleteMenu, or
  38110. ClearMenuBar), and later restore the saved menu list with SetMenuBar. To release the
  38111. memory occupied by the saved menu list, use the Memory Manager procedure DisposHandle.
  38112.  
  38113. Warning:  GetMenuBar doesn’t copy the menus themselves, only a list
  38114.           containing their handles. Do not dispose of any menus that
  38115.           might be in a saved menu list.
  38116.  
  38117. æKY SetMenuBar
  38118. æFc Menus.h
  38119. æT Function
  38120. æTN A93C
  38121. æD pascal void SetMenuBar(Handle menuList)
  38122.     = 0xA93C; 
  38123. æDT SetMenuBar((Handle) menuList);
  38124. æRT 180
  38125. æRI I-355, P-102, 180
  38126. æC 
  38127. SetMenuBar copies the given menu list to the current menu list. You can use this
  38128. procedure to restore a menu list previously saved by GetMenuBar, or pass it a handle
  38129. returned by GetNewMBar. Be sure to call DrawMenuBar to update the menu bar.
  38130.  
  38131. æKY InsMenuItem
  38132. æFc Menus.h
  38133. æT Function
  38134. æTN A826
  38135. æD pascal void InsMenuItem(MenuHandle theMenu,const Str255 itemString,short afterItem)
  38136.     = 0xA826; 
  38137. æDT InsMenuItem((MenuHandle) theMenu,(const Str255) itemString,(short) afterItem);
  38138. æMM
  38139. æRI IV-55
  38140. æC 
  38141. InsMenuItem inserts an item or items into the given menu where specified by the
  38142. afterItem parameter. If afterItem is 0, the items are inserted before the first menu
  38143. item; if it’s the item number of an item in the menu, they’re inserted after that
  38144. item; if it’s equal to or greater than the last item number, they’re appended to the
  38145. menu.
  38146.  
  38147. The contents of itemString are parsed as in the AppendMenu procedure. Multiple items
  38148. are inserted in the reverse of their order in itemString.
  38149.  
  38150. æKY DelMenuItem
  38151. æFc Menus.h
  38152. æT Function
  38153. æTN A952
  38154. æD pascal void DelMenuItem(MenuHandle theMenu,short item)
  38155.     = 0xA952; 
  38156. æDT DelMenuItem((MenuHandle) theMenu,(short) item);
  38157. æMM
  38158. æRI IV-56, V-244
  38159. æC 
  38160. DelMenuItem removes the item’s color entry from the menu color information table, and
  38161. then deletes the item.
  38162.  
  38163. Note:  DelMenuItem is intended for maintaining dynamic menus (such as a
  38164.        list of open windows). It should not be used for disabling items;
  38165.        you should use DisableItem instead.
  38166.  
  38167. æKY MenuKey
  38168. æFc Menus.h
  38169. æT Function
  38170. æTN A93E
  38171. æD pascal long MenuKey(short ch)
  38172.     = 0xA93E; 
  38173. æDT long myVariable = MenuKey((short) ch);
  38174. æMM
  38175. æRI I-356, V-245, P-105, 176
  38176. æC 
  38177. MenuKey maps the given character to the associated menu and item for that character.
  38178. When you get a key-down event with the Command key held down—or an auto-key event, if
  38179. the command being invoked is repeatable—call MenuKey with the character that was
  38180. typed. MenuKey highlights the appropriate menu title, and returns a long integer
  38181. containing the menu ID in its high-order word and the menu item number in its low-order
  38182. word, just as MenuSelect does (see Figure 4 above). After performing the chosen task,
  38183. your application should call HiliteMenu(0) to remove the highlighting from the menu
  38184. title.
  38185.  
  38186. If the given character isn’t associated with any enabled menu item currently in the
  38187. menu list, MenuKey returns 0 in the high-order word of the long integer, and the
  38188. low-order word is undefined.
  38189.  
  38190. If the given character invokes a menu item in a menu belonging to a desk accessory,
  38191. MenuKey (like MenuSelect) passes the menu ID and item number to the Desk Manager
  38192. procedure SystemMenu for processing, and returns 0 to your application in the high-order
  38193. word of the result.
  38194.  
  38195. Note:  There should never be more than one item in the menu list with the
  38196.        same keyboard equivalent, but if there is, MenuKey returns the first
  38197.        such item it encounters, scanning the menus from right to left and
  38198.        their items from top to bottom.
  38199.  
  38200. The MenuKey routine first searches for the given key in the regular portion of the
  38201. MenuList, and if it doesn’t find it there, searches for the key in the hierarchical
  38202. portion of the MenuList. If the key is in a hierarchical menu, MenuKey highlights the
  38203. menu title of the menu that “owns” the hierarchical menu. Ownership in this case
  38204. means the menu in the menu bar that the user would first encounter on the way to the
  38205. item with the given Command-key equivalent. Because several levels of hierarchy are
  38206. possible, this traversal may not always be obvious to the user. As before, after
  38207. performing the chosen task, your application should call HiliteMenu(0) to remove the
  38208. highlighting from the menu title.
  38209.  
  38210. Note:  The Command-key codes $1B (Control-[ ) through $1F (Control- _ ) are
  38211.        reserved by Apple Computer to indicate meanings other than Command-key
  38212.        equivalents. These key codes are ignored by MenuKey, and a result of
  38213.        zero is always returned. Applications must never use these codes for
  38214.        their own use.
  38215.  
  38216. The global variable TheMenu contains the ID of the highlighted menu in the menu bar.
  38217. If an item from a hierarchical menu is chosen, TheMenu contains the ID of the “owner”
  38218. menu, not the ID of the hierarchical menu.
  38219.  
  38220. It’s possible, although undesirable, to define so-called “circular” hierarchical
  38221. menus. A circular hierarchical menu is one in which a submenu has an “ancestor” that
  38222. is also one of its “offspring”. If MenuKey detects circular hierarchical menus, a
  38223. SysError = 86 = #DSHMenuFndErr is generated.
  38224.  
  38225. æKY HiliteMenu
  38226. æFc Menus.h
  38227. æT Function
  38228. æTN A938
  38229. æD pascal void HiliteMenu(short menuID)
  38230.     = 0xA938; 
  38231. æDT HiliteMenu((short) menuID);
  38232. æMM
  38233. æRI I-357, V-245
  38234. æC 
  38235. HiliteMenu highlights the title of the given menu, or does nothing if the title is
  38236. already highlighted. Since only one menu title can be highlighted at a time, it
  38237. unhighlights any previously highlighted menu title. If menuID is 0 (or isn’t the ID
  38238. of any menu in the menu list), HiliteMenu simply unhighlights whichever menu title is
  38239. highlighted (if any).
  38240.  
  38241. After MenuSelect or MenuKey, your application should perform the chosen task and then
  38242. call HiliteMenu(0) to unhighlight the chosen menu title.
  38243.  
  38244. Assembly-language note:  The global variable TheMenu contains the menu ID
  38245.                          of the currently highlighted menu.
  38246.  
  38247. Previously, highlighting a menu title meant inverting the title rectangle, and dehighlighting
  38248. it meant reinverting it, so that it returned to normal.  With color titles, color
  38249. inversion is usually aesthetically unacceptable, so there is a need to draw the
  38250. highlighted menu title.
  38251.  
  38252. HiliteMenu begins by restoring the bits behind the currently highlighted title
  38253. (if there is one). It then saves the bits behind the title rectangle, and draws the
  38254. highlighted title. HiliteMenu(0) dehighlights the currently highlighted menu by
  38255. restoring the bits behind the title.
  38256.  
  38257. Note:  Because an application can only save the bits behind the menu title,
  38258.        only one menu title can be highlighted at a time.
  38259.  
  38260. æKY SetItem
  38261. æFc Menus.h
  38262. æT Function
  38263. æTN A947
  38264. æD pascal void SetItem(MenuHandle theMenu,short item,const Str255 itemString)
  38265.     = 0xA947; 
  38266. æDT SetItem((MenuHandle) theMenu,(short) item,(const Str255) itemString);
  38267. æMM
  38268. æRI I-357, P-104, 180
  38269. æC 
  38270. SetItem changes the text of the given menu item to itemString. It doesn’t recognize
  38271. the meta-characters used in AppendMenu; if you include them in itemString, they will
  38272. appear in the text of the menu item. The attributes already in effect for this item—its
  38273. character style, icon, and so on—remain in effect. ItemString may be blank but should
  38274. not be the empty string.
  38275.  
  38276. Note:  It’s good practice to store the text of itemString in a resource
  38277.        file instead of passing it directly.
  38278.  
  38279. Use SetItem to change between the two forms of a toggled command—for example, to
  38280. change “Show Clipboard” to “Hide Clipboard” when the Clipboard is already showing.
  38281.  
  38282. Note:  To avoid confusing the user, don’t capriciously change the text
  38283.        of menu items.
  38284.  
  38285. æKY GetItem
  38286. æFc Menus.h
  38287. æT Function
  38288. æTN A946
  38289. æD pascal void GetItem(MenuHandle theMenu,short item,Str255 itemString)
  38290.     = 0xA946; 
  38291. æDT GetItem((MenuHandle) theMenu,(short) item,(Str255) itemString);
  38292. æRI I-358, P-104, 172
  38293. æC 
  38294. GetItem returns the text of the given menu item in itemString. It doesn’t place any
  38295. meta-characters in the string. This procedure is useful for getting the name of a
  38296. menu item that was installed with AddResMenu or InsertResMenu.
  38297.  
  38298. æKY DisableItem
  38299. æFc Menus.h
  38300. æT Function
  38301. æTN A93A
  38302. æD pascal void DisableItem(MenuHandle theMenu,short item)
  38303.     = 0xA93A; 
  38304. æDT DisableItem((MenuHandle) theMenu,(short) item);
  38305. æRI I-358, V-245, P-104, 168
  38306. æC 
  38307. Given a menu item number in the item parameter, DisableItem disables that menu item;
  38308. given 0 in the item parameter, it disables the entire menu.
  38309.  
  38310. Disabled menu items appear dimmed and are not highlighted when the cursor moves over
  38311. them. MenuSelect and MenuKey return 0 in the high-order word of their result if the
  38312. user attempts to invoke a disabled item. Use DisableItem to disable all menu choices
  38313. that aren’t appropriate at a given time (such as a Cut command when there’s no text
  38314. selection).
  38315.  
  38316. All menu items are initially enabled unless you specify otherwise (such as by using
  38317. the “(” meta- character in a call to AppendMenu).
  38318.  
  38319. When you disable an entire menu, call DrawMenuBar to update the menu bar. The title
  38320. of a disabled menu and every item in it are dimmed.
  38321.  
  38322. The EnableItem and DisableItem routines provide enable flags that can handle the
  38323. title and 31 menu items. All items greater than 31 will be ignored by these calls and
  38324. will always be enabled.
  38325.  
  38326. æKY EnableItem
  38327. æFc Menus.h
  38328. æT Function
  38329. æTN A939
  38330. æD pascal void EnableItem(MenuHandle theMenu,short item)
  38331.     = 0xA939; 
  38332. æDT EnableItem((MenuHandle) theMenu,(short) item);
  38333. æRI I-358, V-245, P-104, 170
  38334. æC  
  38335. Given a menu item number in the item parameter, EnableItem enables the item
  38336. (which may have been disabled with the DisableItem procedure, or with the “(” meta-character
  38337. in the AppendMenu string).
  38338.  
  38339. Given 0 in the item parameter, EnableItem enables the menu as a whole, but any items
  38340. that were disabled separately (before the entire menu was disabled) remain so. When
  38341. you enable an entire menu, call DrawMenuBar to update the menu bar.
  38342.  
  38343. The item or menu title will no longer appear dimmed and can be chosen like any other
  38344. enabled item or menu.
  38345.  
  38346. æKY CheckItem
  38347. æFc Menus.h
  38348. æT Function
  38349. æTN A945
  38350. æD pascal void CheckItem(MenuHandle theMenu,short item,Boolean checked)
  38351.     = 0xA945; 
  38352. æDT CheckItem((MenuHandle) theMenu,(short) item,(Boolean) checked);
  38353. æMM
  38354. æRI I-358
  38355. æC 
  38356. CheckItem places or removes a check mark at the left of the given menu item. After
  38357. you call CheckItem with checked=TRUE, a check mark will appear each subsequent time
  38358. the menu is pulled down. Calling CheckItem with checked=FALSE removes the check mark
  38359. from the menu item (or, if it’s marked with a different character, removes that
  38360. mark).
  38361.  
  38362. Menu items are initially unmarked unless you specify otherwise (such as with the “!”
  38363. meta-character in a call to AppendMenu).
  38364.  
  38365. æKY SetItemMark
  38366. æFc Menus.h
  38367. æT Function
  38368. æTN A944
  38369. æD pascal void SetItemMark(MenuHandle theMenu,short item,short markChar)
  38370.     = 0xA944; 
  38371. æDT SetItemMark((MenuHandle) theMenu,(short) item,(short) markChar);
  38372. æMM
  38373. æRI I-359, V-246
  38374. æC 
  38375. Assembly-language note:  The macro you invoke to call SetItemMark from
  38376.                          assembly language is named _SetItmMark.
  38377.  
  38378. SetItemMark marks the given menu item in a more general manner than CheckItem. It
  38379. allows you to place any character in the system font, not just the check mark, to the
  38380. left of the item. The character is passed in the markChar parameter.
  38381.  
  38382. Note:  The Font Manager defines constants for the check mark and other special
  38383.        characters that can’t normally be typed from the keyboard:  the apple
  38384.        symbol, the Command key symbol, and a diamond symbol. See the Font
  38385.        Manager chapter for more information.
  38386.  
  38387. To remove an item’s mark, you can pass the following predefined constant in the
  38388. markChar parameter:
  38389.  
  38390. CONST noMark = 0;
  38391.  
  38392. The SetItemMark procedure allows the application to change the submenu associated
  38393. with a menu item.
  38394.  
  38395. æKY GetItemMark
  38396. æFc Menus.h
  38397. æT Function
  38398. æTN A943
  38399. æD pascal void GetItemMark(MenuHandle theMenu,short item,short *markChar)
  38400.     = 0xA943; 
  38401. æDT GetItemMark((MenuHandle) theMenu,(short) item,(short *) markChar);
  38402. æRI I-359, V-246
  38403. æC 
  38404. Assembly-language note:  The macro you invoke to call GetItemMark from
  38405.                          assembly language is named _GetItmMark.
  38406.  
  38407. GetItemMark returns in markChar whatever character the given menu item is marked
  38408. with, or the predefined constant noMark if no mark is present.
  38409.  
  38410. The GetItemMark procedure may be used to determine the ID of the hierarchical menu
  38411. associated with a menu item.
  38412.  
  38413. æKY SetItemIcon
  38414. æFc Menus.h
  38415. æT Function
  38416. æTN A940
  38417. æD pascal void SetItemIcon(MenuHandle theMenu,short item,short icon)
  38418.     = 0xA940; 
  38419. æDT SetItemIcon((MenuHandle) theMenu,(short) item,(short) icon);
  38420. æMM
  38421. æRI I-359, V-246
  38422. æC 
  38423. Assembly-language note:  The macro you invoke to call SetItemIcon from
  38424.                          assembly language is named _SetItmIcon.
  38425.  
  38426. SetItemIcon associates the given menu item with an icon. It sets the item’s icon
  38427. number to the given value (an integer from 1 to 255). The Menu Manager adds 256 to
  38428. the icon number to get the icon’s resource ID, which it passes to the Resource Manager
  38429. to get the corresponding icon.
  38430.  
  38431. Warning:  If you call the Resource Manager directly to read or store
  38432.           menu icons, be sure to adjust your icon numbers accordingly.
  38433.  
  38434. Menu items initially have no icons unless you specify otherwise (such as with the “^”
  38435. meta-character in a call to AppendMenu).
  38436.  
  38437. The SetItemIcon procedure should never be called for font items that are international
  38438. scripts, unless the intention is to change the script number
  38439. (there should never be any need to do this).
  38440.  
  38441. æKY GetItemIcon
  38442. æFc Menus.h
  38443. æT Function
  38444. æTN A93F
  38445. æD pascal void GetItemIcon(MenuHandle theMenu,short item,short *iconNum)
  38446.     = 0xA93F; 
  38447. æDT GetItemIcon((MenuHandle) theMenu,(short) item,(short *) iconNum);
  38448. æRI I-360, V-246
  38449. æC 
  38450. Assembly-language note:  The macro you invoke to call GetItemIcon from
  38451.                          assembly language is named _GetItmIcon.
  38452.  
  38453. GetItemIcon returns the icon number associated with the given menu item, as an integer
  38454. from 1 to 255, or 0 if the item has not been associated with an icon. The icon number
  38455. is 256 less than the icon’s resource ID.
  38456.  
  38457. The GetItemIcon procedure may be used to determine the script number of a font item
  38458. that is the name of an international script.
  38459.  
  38460. æKY SetItemStyle
  38461. æFc Menus.h
  38462. æT Function
  38463. æTN A942
  38464. æD pascal void SetItemStyle(MenuHandle theMenu,short item,Short chStyle)
  38465.     = 0xA942; 
  38466. æDT SetItemStyle((MenuHandle) theMenu,(short) item,(Short) chStyle);
  38467. æMM
  38468. æRI I-360
  38469. æC 
  38470. Assembly-language note:  The macro you invoke to call SetItemStyle from
  38471.                          assembly language is named _SetItmStyle.
  38472.  
  38473. SetItemStyle changes the character style of the given menu item to chStyle. For
  38474. example:
  38475.  
  38476.   SetItemStyle(thisMenu,1,[bold,italic])    {bold and italic}
  38477.  
  38478. Menu items are initially in the plain character style unless you specify otherwise
  38479. (such as with the “<” meta-character in a call to AppendMenu).
  38480.  
  38481. æKY GetItemStyle
  38482. æFc Menus.h
  38483. æT Function
  38484. æTN A941
  38485. æD pascal void GetItemStyle(MenuHandle theMenu,short item,Style *chStyle); 
  38486. æDT GetItemStyle((MenuHandle) theMenu,(short) item,(Style *) chStyle);
  38487. æRI I-360, V-247, N61-1
  38488. æC 
  38489. Assembly-language note:  The macro you invoke to call GetItemStyle from
  38490.                          assembly language is named _GetItmStyle.
  38491.  
  38492. GetItemStyle returns the character style of the given menu item in chStyle.
  38493.  
  38494. There is a possible bug in this routine, depending on the interpretation of the
  38495. address of the VAR parameter chStyle. GetItemStyle assumes that the address on the
  38496. stack points to a word with chStyle in the low byte. MPW Pascal passes the byte
  38497. address of chStyle regardless of whether it’s in the high or low byte of a word.
  38498. Since there has never been a bug report for this “problem”, it is listed here for
  38499. information only.
  38500.  
  38501. æKY CalcMenuSize
  38502. æFc Menus.h
  38503. æT Function
  38504. æTN A948
  38505. æD pascal void CalcMenuSize(MenuHandle theMenu)
  38506.     = 0xA948; 
  38507. æDT CalcMenuSize((MenuHandle) theMenu);
  38508. æMM
  38509. æRI I-361
  38510. æC 
  38511. You can use CalcMenuSize to recalculate the horizontal and vertical dimensions of a
  38512. menu whose contents have been changed (and store them in the appropriate fields of
  38513. the menu record). CalcMenuSize is called internally by the Menu Manager after every
  38514. routine that changes a menu.
  38515.  
  38516. æKY CountMItems
  38517. æFc Menus.h
  38518. æT Function
  38519. æTN A950
  38520. æD pascal short CountMItems(MenuHandle theMenu)
  38521.     = 0xA950; 
  38522. æDT short myVariable = CountMItems((MenuHandle) theMenu);
  38523. æRI I-361
  38524. æC 
  38525. CountMItems returns the number of menu items in the given menu.
  38526.  
  38527. æKY GetMHandle
  38528. æFc Menus.h
  38529. æT Function
  38530. æTN A949
  38531. æD pascal MenuHandle GetMHandle(short menuID)
  38532.     = 0xA949; 
  38533. æDT MenuHandle myVariable = GetMHandle((short) menuID);
  38534. æRI I-361, V-246
  38535. æC 
  38536. Given the menu ID of a menu currently installed in the menu list, GetMHandle returns
  38537. a handle to that menu; given any other menu ID, it returns NIL.
  38538.  
  38539. The GetMHandle routine looks for the menu in the hierarchical portion of the MenuList
  38540. first, and if it isn’t found, looks in the regular portion of the MenuList. The
  38541. routine has no way to determine whether the returned menu is associated with a menu,
  38542. pop-up, or hierarchical menu. Presumably the application will contain that information.
  38543.  
  38544. æKY FlashMenuBar
  38545. æFc Menus.h
  38546. æT Function
  38547. æTN A94C
  38548. æD pascal void FlashMenuBar(short menuID)
  38549.     = 0xA94C; 
  38550. æDT FlashMenuBar((short) menuID);
  38551. æMM
  38552. æRI I-361, V-246
  38553. æC 
  38554. If menuID is 0 (or isn’t the ID of any menu in the menu list), FlashMenuBar inverts
  38555. the entire menu bar; otherwise, it inverts the title of the given menu. You can call
  38556. FlashMenuBar(0) twice to blink the menu bar.
  38557.  
  38558. FlashMenuBar(0) still inverts the complete menu bar. Strange colors may result if
  38559. HiliteMenu, or FlashMenuBar with a nonzero parameter, are called while the menu bar
  38560. is inverted.
  38561.  
  38562. FlashMenuBar has been modified so that only one menu may be highlighted at a time
  38563. (see HiliteMenu). If no menu is currently highlighted, calling FlashMenuBar with a
  38564. nonzero parameter highlights that menu. If  the highlighted menu is different than
  38565. the one being “flashed”, the previously highlighted menu is first restored to normal,
  38566. and the new menu is highlighted.
  38567.  
  38568. æKY SetMenuFlash
  38569. æFc Menus.h
  38570. æT Function
  38571. æTN A94A
  38572. æD pascal void SetMenuFlash(short count)
  38573.     = 0xA94A; 
  38574. æDT SetMenuFlash((short) count);
  38575. æRI I-361
  38576. æC 
  38577. Assembly-language note:  The macro you invoke to call SetMenuFlash from
  38578.                          assembly language is named _SetMFlash.
  38579.  
  38580. When the mouse button is released over an enabled menu item, the item blinks briefly
  38581. to confirm the choice. Normally, your application shouldn’t be concerned with this
  38582. blinking; the user sets it with the Control Panel desk accessory. If you’re writing a
  38583. desk accessory like the Control Panel, though, SetMenuFlash allows you to control the
  38584. duration of the blinking. The count parameter is the number of times menu items will
  38585. blink; it’s initially 3 if the user hasn’t changed it. A count of 0 disables blinking.
  38586. Values greater than 3 can be annoyingly slow.
  38587.  
  38588. Note:  Items in both standard and nonstandard menus blink when chosen. The
  38589.        appearance of the blinking for a nonstandard menu depends on the menu
  38590.        definition procedure, as described in “Defining Your Own Menus”.
  38591.  
  38592. Assembly-language note:  The current count is stored in the global
  38593.                          variable MenuFlash.
  38594.  
  38595. æKY MenuSelect
  38596. æFc Menus.h
  38597. æT Function
  38598. æTN A93D
  38599. æD pascal long MenuSelect(Point startPt)
  38600.     = 0xA93D; 
  38601. æDT long myVariable = MenuSelect((Point) startPt);
  38602. æMM
  38603. æRI I-355, V-244, P-36, 103, 105, 176
  38604. æC 
  38605. When there’s a mouse-down event in the menu bar, the application should call MenuSelect
  38606. with startPt equal to the point (in global coordinates) where the mouse button was
  38607. pressed. MenuSelect keeps control until the mouse button is released, tracking the
  38608. mouse, pulling down menus as needed, and highlighting enabled menu items under the
  38609. cursor. When the mouse button is released over an enabled item in an application
  38610. menu, MenuSelect returns a long integer whose high-order word is the menu ID of the
  38611. menu, and whose low-order word is the menu item number for the item chosen (see
  38612. Figure 4). It leaves the selected menu title highlighted. After performing the chosen
  38613. task, your application should call HiliteMenu(0) to remove the highlighting from the
  38614. menu title.
  38615.  
  38616. If no choice is made, MenuSelect returns 0 in the high-order word of the long integer,
  38617. and the low-order word is undefined. This includes the case where the mouse button is
  38618. released over a disabled menu item (such as Cut, Copy, Clear, or one of the dividing
  38619. lines in Figure 4), over any menu title, or outside the menu.  In the case of a
  38620. disabled menu item, an application can still determine which item was chosen.  See
  38621. the description of the MenuChoice routine for further details.
  38622.  
  38623. If the mouse button is released over an enabled item in a menu belonging to a desk
  38624. accessory, MenuSelect passes the menu ID and item number to the Desk Manager procedure
  38625. SystemMenu for processing, and returns 0 to your application in the high-order word
  38626. of the result.
  38627.  
  38628. Note:  When a menu is pulled down, the bits behind it are stored as a
  38629.        relocatable object in the application heap. If your application
  38630.        has large menus, this can temporarily use up a lot of memory.
  38631.  
  38632. •••Refer to Figure 4.•••
  38633.  
  38634. Figure 4–MenuSelect and MenuKey
  38635.  
  38636. Assembly-language note:  If the global variable MBarEnable is nonzero,
  38637.                          MenuSelect knows that every menu currently in
  38638.                          the menu bar belongs to a desk accessory. (See
  38639.                          the Desk Manager chapter for more information.)
  38640.  
  38641.                          You can store in the global variables MenuHook and
  38642.                          MBarHook the addresses of routines that will be called
  38643.                          during MenuSelect. Both variables are initialized to
  38644.                          0 by InitMenus. The routine whose address is in
  38645.                          MenuHook (if any) will be called repeatedly (with no
  38646.                          parameters) while the mouse button is down. The
  38647.                          routine whose address is in MBarHook (if any) will
  38648.                          be called after the title of the menu is highlighted
  38649.                          and the menu rectangle is calculated, but before the
  38650.                          menu is drawn. (The menu rectangle is the rectangle in
  38651.                          which the menu will be drawn, in global coordinates.)
  38652.                          The routine is passed a pointer to the menu rectangle
  38653.                          on the stack. It should normally return 0 in register
  38654.                          D0; returning 1 will abort MenuSelect.
  38655.  
  38656. If the user chooses an item with a submenu, MenuSelect returns zero, meaning that no
  38657. item was selected. If the user selects an item from a hierarchical menu, the menuID
  38658. of the hierarchical menu and the menuItem of the item chosen are returned, just as
  38659. though the item had been in a regular menu.
  38660.  
  38661. If MenuSelect returns zero, an application may call MenuChoice to determine whether
  38662. the mouse was released over either a disabled menu item or an item with a submenu.
  38663.  
  38664. Note:  The global variable TheMenu contains the ID of the highlighted menu in
  38665.        the menu bar. If an item from a hierarchical menu is chosen, TheMenu
  38666.        contains the ID of the “owner” menu, not the ID of the hierarchical menu.
  38667.  
  38668. æKY InitProcMenu
  38669. æFc Menus.h
  38670. æT Function
  38671. æTN A808
  38672. æD pascal void InitProcMenu(short resID)
  38673.     = 0xA808; 
  38674. æDT InitProcMenu((short) resID);
  38675. æMM
  38676. æRI V-238
  38677. æC 
  38678. [Macintosh Plus, Macintosh SE, Macintosh II]
  38679.  
  38680. Note:  The mbVariant field is contained in the low three bits of the
  38681.        mbResID. The high order 13 bits are used to load the proper 'MBDF'.
  38682.  
  38683. The InitProcMenu routine is called when an application has a custom menu bar defproc,
  38684. 'MBDF'. InitProcMenu allocates a new MenuList if it hasn’t already been allocated by
  38685. a previous call to InitMenus, and the mbResID is stored in the mbResID field in the
  38686. MenuList (note that InitWindows calls InitMenus, so that it can obtain the menu bar
  38687. height).
  38688.  
  38689. The effect of InitProcMenu lasts for the duration of the application only; the next
  38690. InitMenus call will replace the mbResID field in the MenuList with the default value
  38691. of zero. This affects applications such as development systems, which use multiple
  38692. heaps and whose “applications” call InitMenus.
  38693.  
  38694. Note:  Apple reserves mbResID values $000–$100 for its own use.
  38695.  
  38696. æKY GetItemCmd
  38697. æFc Menus.h
  38698. æT Function
  38699. æTN A84E
  38700. æD pascal void GetItemCmd(MenuHandle theMenu,short item,short *cmdChar)
  38701.     = 0xA84E; 
  38702. æDT GetItemCmd((MenuHandle) theMenu,(short) item,(short *) cmdChar);
  38703. æRI V-240
  38704. æC 
  38705. [Macintosh Plus, Macintosh SE, Macintosh II]
  38706.  
  38707. The GetItemCmd routine may be used to determine whether a menu item has a submenu
  38708. attached. For a menu item with a submenu, the returned cmdChar will have the value
  38709. $1B.
  38710.  
  38711. æKY SetItemCmd
  38712. æFc Menus.h
  38713. æT Function
  38714. æTN A84F
  38715. æD pascal void SetItemCmd(MenuHandle theMenu,short item,short cmdChar)
  38716.     = 0xA84F; 
  38717. æDT SetItemCmd((MenuHandle) theMenu,(short) item,(short) cmdChar);
  38718. æRI V-240
  38719. æC 
  38720. [Macintosh Plus, Macintosh SE, Macintosh II]
  38721.  
  38722. The SetItemCmd routine allows the application to attach a submenu to a menu by passing
  38723. the character $1B. You should be careful about arbitrarily adding or removing a
  38724. submenu from a menu item; see the Macintosh User Interface Guidelines chapter for
  38725. recommendations. Notice that SetItemMark can be used to change the ID of the submenu
  38726. that is associated with the menu item.
  38727.  
  38728. Note:  SetItemCmd must never be used to change the Command-key value of a
  38729.        menu item that doesn’t have a submenu; users must always be free to
  38730.        change their Command-key preferences.
  38731.  
  38732. æKY PopUpMenuSelect
  38733. æFc Menus.h
  38734. æT Function
  38735. æTN A80B
  38736. æD pascal long PopUpMenuSelect(MenuHandle menu,short top,short left,short popUpItem)
  38737.     = 0xA80B; 
  38738. æDT long myVariable = PopUpMenuSelect((MenuHandle) menu,(short) top,(short) left,(short) popUpItem);
  38739. æMM
  38740. æRT 156
  38741. æRI V-241, N156-2
  38742. æC 
  38743. [Macintosh Plus, Macintosh SE, Macintosh II]
  38744.  
  38745. The PopUpMenuSelect routine allows an application to create a pop-up menu anywhere on
  38746. the screen. This menu may be colored like any other menu, and it may have submenus.
  38747. The return value is the same as that for MenuSelect, where the low word is the menu
  38748. item selected, and the high word is the menu ID. Unlike MenuSelect, PopUpMenuSelect
  38749. doesn’t highlight any of the menus in the menu bar, so HiliteMenu(0) doesn’t have to
  38750. be called after completing the chosen task.
  38751.  
  38752. Pop-up menus are typically used for lists of items, for example, fonts. See the
  38753. Macintosh User Interface Guidelines chapter for a description of how to use pop-up
  38754. menus in your application. See MenuSelect for information about the return value when
  38755. the menu chosen is a hierarchical menu.
  38756.  
  38757. TheMenu is a handle to the menu that you want “popped up”. The PopUpItem is typically
  38758. the currently selected item, that is, the last item selected, or the first item if
  38759. nothing was selected. Doing this allows the user to click on a pop-up menu and release
  38760. again quickly, without changing the item selection by mistake. The parameters Top and
  38761. Left define where the top left corner of the PopUpItem is to appear, in global coordinates.
  38762. Typically, these will be the top left coordinates of the pop-up box, so that the menu
  38763. item appears on top of the pop-up box. See Figure 5 for an example.
  38764.  
  38765. •••Refer to Figure 5.•••
  38766.  
  38767. Figure 5–Pop-up Box Parameters
  38768.  
  38769. »Drawing the Pop-Up Box
  38770.  
  38771. Your application is responsible for drawing the pop-up box. A pop-up box is a rectangle
  38772. that is the same height as the menu item, is wide enough to show the currently selected
  38773. item, and has a one-pixel-wide drop shadow.
  38774.  
  38775. The pop-up box must be the same height as a menu item so that when the menu appears,
  38776. the cursor will be in the previously chosen item. If the pop-up box is too tall, the
  38777. user could click once quickly in a pop-up box and unintentionally choose a different
  38778. menu item. The height of a menu item in the system font is the ascent + descent +
  38779. leading.
  38780.  
  38781. The pop-up box has a title to its left. The application is responsible for recognizing
  38782. a mouse-down event in the pop-up box, and highlighting the title to the left of the
  38783. pop-up menu box before calling MenuSelect. Similarly, the application is responsible
  38784. for highlighting the title if the pop-up menu has Command-key equivalents.
  38785.  
  38786. Before calling PopUpMenuSelect, the pop-up menu must be installed in the hierarchical
  38787. portion of the MenuList by passing a value of  –1 as the “beforeID” to InsertMenu.
  38788.  
  38789. The following is a sample psuedocode stub that might be used to track a pop-up menu:
  38790.  
  38791.   if mouse is in popUpMenuRect then  
  38792.       myInvertPopUpTitle();               {invert title of pop-up menu}
  38793.       InsertMenu(popupMenuHandle, -1);    {-1 means hierarchical menu}
  38794.       Result = PopUpMenuSelect(popUpMenuHandle, popUpRect.Top,
  38795.                                popUpRect.Left, lastItemSelected);
  38796.       DeleteMenu(popUpMenuID);
  38797.       myInvertPopUpTitle();               {return pop-up title to normal}
  38798.   endif
  38799.  
  38800. Notice that PopUpMenuSelect’s sole function is to display the pop-up menu and track
  38801. the mouse during a mouse-down event. It is the application’s responsibility to handle
  38802. all other pop-up menu functions, such as drawing the pop-up box, drawing and highlighting
  38803. the title, and changing the entry in the pop-up box after an item has been chosen
  38804. from the pop-up menu. This could all be handled by creating a pop-up menu control
  38805. within the application.
  38806.  
  38807. When calling PopUpMenuSelect, the pop-up menu must be in the MenuList for the duration
  38808. of the call. The code above shows a call the InsertMenu before, and a call to DeleteMenu
  38809. after, the call to PopUpMenuSelect. The InsertMenu must be used at some time before
  38810. the call to PopUpMenuSelect, but it’s not necessary to call DeleteMenu immediately
  38811. afterwards; the pop-up menu may be left in the MenuList if desired.
  38812.  
  38813. Pop-up menu items can have Command-key equivalents. The application must provide
  38814. sufficient visual feedback, normally provided by using MenuKey, by inverting the
  38815. pop-up title.
  38816.  
  38817. æKY MenuChoice
  38818. æFc Menus.h
  38819. æT Function
  38820. æTN AA66
  38821. æD pascal long MenuChoice(void)
  38822.     = 0xAA66; 
  38823. æDT long myVariable = MenuChoice()(void);
  38824. æRI V-240, P-103, 105, 176
  38825. æC 
  38826. [Macintosh II]
  38827.  
  38828. The MenuChoice routine is called only after the result from MenuSelect is zero. It
  38829. determines if the mouse-up event that terminated MenuSelect was in a disabled menu
  38830. item. When the mouse button is released over a disabled item in an application menu,
  38831. MenuChoice returns a long integer whose high-order word is the menuID of the menu,
  38832. and whose low-order word is the menu item number for the disabled item “chosen”. If
  38833. the item number is zero, then the mouse-up event occurred when the mouse was either
  38834. in the menu title or completely outside the menu; there is no way to distinguish
  38835. between the two.
  38836.  
  38837. Note:  This information is available on the Macintosh Plus and Macintosh SE
  38838.        by directly querying the long word stored in the global variable
  38839.        MenuDisable ($B54).
  38840.  
  38841. This feature has been added to MenuChoice to make it possible for applications to
  38842. provide better help facilities. For example, when the Finder calls MenuChoice, and
  38843. determines that a user has chosen the disabled menu item “Empty Trash” with the
  38844. Finder, the application could display a message telling the user that it can’t empty
  38845. the trash because there is nothing currently in the trash.
  38846.  
  38847. The new MenuChoice capability is implemented by continual updates of the global
  38848. variable MenuDisable ($B54) whenever a menu is down. As the mouse moves over each
  38849. item, MenuDisable is updated to reflect the current menu and item ID. The code that
  38850. changes the value in MenuDisable resides in the standard menu defproc. The return
  38851. value is undefined when the menu uses a custom menu defproc, unless the custom defproc
  38852. also supports this feature.
  38853.  
  38854. æKY DelMCEntries
  38855. æFc Menus.h
  38856. æT Function
  38857. æTN AA60
  38858. æD pascal void DelMCEntries(short menuID,short menuItem)
  38859.     = 0xAA60; 
  38860. æDT DelMCEntries((short) menuID,(short) menuItem);
  38861. æMM
  38862. æRI V-238
  38863. æC 
  38864. [Macintosh II]
  38865.  
  38866. The DelMCEntries routine deletes entries from the menu color information table based
  38867. on the given menuID and menuItem. If the entry is not found, no entry is removed. If
  38868. the menuItem is mctAllItems (–98), then all Items for the specified ID are removed.
  38869.  
  38870. Applications must, of course, never delete the last entry in the menu color information
  38871. table.
  38872.  
  38873. æKY GetMCInfo
  38874. æFc Menus.h
  38875. æT Function
  38876. æTN AA61
  38877. æD pascal MCTableHandle GetMCInfo(void)
  38878.     = 0xAA61; 
  38879. æDT MCTableHandle myVariable = GetMCInfo()(void);
  38880. æMM
  38881. æRI V-239
  38882. æC 
  38883. [Macintosh II]
  38884.  
  38885. The GetMCInfo routine creates a copy of the current menu color information table and
  38886. returns a handle to the copy. It doesn’t affect the current menu color information
  38887. table. If the copy fails, a NIL handle is returned.
  38888.  
  38889. æKY SetMCInfo
  38890. æFc Menus.h
  38891. æT Function
  38892. æTN AA62
  38893. æD pascal void SetMCInfo(MCTableHandle menuCTbl)
  38894.     = 0xAA62; 
  38895. æDT SetMCInfo((MCTableHandle) menuCTbl);
  38896. æMM
  38897. æRI V-239
  38898. æC 
  38899. [Macintosh II]
  38900.  
  38901. The SetMCInfo routine copies the given menu color information table to the current
  38902. menu color information table. It first disposes of the current menu color information
  38903. table, so your application shouldn’t explicitly dispose the current table. If the
  38904. copy fails, the global variable MemErr contains the error code, and the procedure
  38905. doesn’t dispose the current menu color information table. Applications should call
  38906. the MemError function to determine if this call failed.
  38907.  
  38908. You can use this procedure to restore a menu color information table previously saved
  38909. by GetMCInfo. Be sure to call DrawMenuBar to update the menu bar if a new menu bar
  38910. color or menu title colors have been specified.
  38911.  
  38912. æKY DispMCInfo
  38913. æFc Menus.h
  38914. æT Function
  38915. æTN AA63
  38916. æD pascal void DispMCInfo(MCTableHandle menuCTbl)
  38917.     = 0xAA63; 
  38918. æDT DispMCInfo((MCTableHandle) menuCTbl);
  38919. æMM
  38920. æRI V-239
  38921. æC 
  38922. [Macintosh II]
  38923.  
  38924. Given a handle to a menu color information table, the DispMCInfo routine disposes of
  38925. the table. No checking is done to determine whether the handle is valid. While this
  38926. procedure currently only calls DisposHandle, to ensure compatibility with any updates
  38927. to the color portion of the menu manager, it’s a good idea to use this call.
  38928.  
  38929. æKY GetMCEntry
  38930. æFc Menus.h
  38931. æT Function
  38932. æTN AA64
  38933. æD pascal MCEntryPtr GetMCEntry(short menuID,short menuItem)
  38934.     = 0xAA64; 
  38935. æDT MCEntryPtr myVariable = GetMCEntry((short) menuID,(short) menuItem);
  38936. æRI V-239
  38937. æC 
  38938. [Macintosh II]
  38939.  
  38940. The GetMCEntry routine finds the entry of the specified menuID and menuItem in the
  38941. menu color information table, and returns a pointer into the table. If the entry is
  38942. not found, a NIL pointer is returned.
  38943.  
  38944. Note:  Entries are not removed from the table. Applications must not remove
  38945.        entries from the table directly; they should always use the procedure
  38946.        DelMCEntries to remove entries.
  38947.  
  38948. Warning:  The menu color information table is relocatable, so the GetMCEntry
  38949.           return value may not be valid across traps that move or purge memory.
  38950.           Applications should make a copy of the record in this case.
  38951.  
  38952. æKY SetMCEntries
  38953. æFc Menus.h
  38954. æT Function
  38955. æTN AA65
  38956. æD pascal void SetMCEntries(short numEntries,MCTablePtr menuCEntries)
  38957.     = 0xAA65; 
  38958. æDT SetMCEntries((short) numEntries,(MCTablePtr) menuCEntries);
  38959. æMM
  38960. æRI V-239
  38961. æC 
  38962. [Macintosh II]
  38963.  
  38964. The SetMCEntries procedure takes a pointer to an array of color information records.
  38965. The array may be of any size, so it’s necessary to also pass the number of entries in
  38966. the array.
  38967.  
  38968. The ID and Item of each entry in the color information record array are checked to
  38969. see if the entry already exists in the menu color information table. If it exists,
  38970. the information in the entry is used to update the entry in the color table. If the
  38971. entry doesn’t exist in the color information table, the entry is added to the table.
  38972.  
  38973. Warning:  SetMCEntries makes memory management calls that may move or purge
  38974.           memory; therefore the array menuCEntries should be nonrelocatable
  38975.           for the duration of this call.
  38976.  
  38977. æKY newmenu
  38978. æFc Menus.h
  38979. æT Function
  38980. æD MenuHandle newmenu(short menuID,char *menuTitle); 
  38981. æDT MenuHandle myVariable = newmenu((short) menuID,(char *) menuTitle);
  38982. æMM
  38983. æRI I-351, P-102, 103
  38984. æC 
  38985. NewMenu allocates space for a new menu with the given menu ID and title, and returns
  38986. a handle to it. It sets up the menu to use the standard menu definition procedure.
  38987. (The menu definition procedure is read into memory if it isn’t already in memory.)
  38988. The new menu (which is created empty) is not installed in the menu list. To use this
  38989. menu, you must first call AppendMenu or AddResMenu to fill it with items, InsertMenu
  38990. to place it in the menu list, and DrawMenuBar to update the menu bar to include the
  38991. new title.
  38992.  
  38993. Application menus should always have positive menu IDs. Negative menu IDs are reserved
  38994. for menus belonging to desk accessories. No menu should ever have a menu ID of 0.
  38995.  
  38996. If you want to set up the title of the Apple menu from your program instead of reading
  38997. it in from a resource file, you can use the constant appleMark (defined by the Font
  38998. Manager as the character code for the apple symbol). For example, you can declare the
  38999. string variable
  39000.  
  39001.   VAR myTitle:  STRING[1];
  39002.  
  39003. and do the following:
  39004.  
  39005.   myTitle := ' ';
  39006.   myTitle[1] := CHR(appleMark)
  39007.  
  39008. To release the memory occupied by a menu that you created with NewMenu, call DisposeMenu.
  39009.  
  39010. æKY getitem
  39011. æFc Menus.h
  39012. æT Function
  39013. æD void getitem(MenuHandle menu,short item,char *itemString); 
  39014. æDT getitem((MenuHandle) menu,(short) item,(char *) itemString);
  39015. æRI I-358, P-104, 172
  39016. æC 
  39017. GetItem returns the text of the given menu item in itemString. It doesn’t place any
  39018. meta-characters in the string. This procedure is useful for getting the name of a
  39019. menu item that was installed with AddResMenu or InsertResMenu.
  39020.  
  39021. æKY appendmenu
  39022. æFc Menus.h
  39023. æT Function
  39024. æD void appendmenu(MenuHandle menu,char *data); 
  39025. æDT appendmenu((MenuHandle) menu,(char *) data);
  39026. æRI I-352, V-243, P-102
  39027. æC  
  39028. AppendMenu adds an item or items to the end of the given menu, which must previously
  39029. have been allocated by NewMenu or read from a resource file by GetMenu. The data
  39030. string consists of the text of the menu item; it may be blank but should not be the
  39031. empty string. If it begins with a hyphen (–), the item will be a dividing line across
  39032. the width of the menu. As described in the section “Creating a Menu in Your Program”,
  39033. the following meta-characters may be embedded in the data string:
  39034.  
  39035.   Meta-character    Usage
  39036.  
  39037.   ; or Return       Separates multiple items
  39038.   ^                 Followed by an icon number, adds that icon to the item
  39039.   !                 Followed by a character, marks the item with that character
  39040.   <                 Followed by B, I, U, O, or S, sets the character style
  39041.                     of the item
  39042.   /                 Followed by a character, associates a keyboard equivalent
  39043.                     with the item
  39044.   (                 Disables the item
  39045.  
  39046. Once items have been appended to a menu, they cannot be removed or rearranged. AppendMenu
  39047. works properly whether or not the menu is in the menu list.
  39048.  
  39049. _______________________________________________________________________________
  39050.  
  39051. »CREATING A MENU IN YOUR PROGRAM
  39052. _______________________________________________________________________________
  39053.  
  39054. The best way to create your application’s menus is to set them up as resources and
  39055. read them in from a resource file. If you want your application to create the menus
  39056. itself, though, it must call the NewMenu and AppendMenu routines. NewMenu creates a
  39057. new menu data structure, returning a handle to it. AppendMenu takes a string and a
  39058. handle to a menu and adds the items in the string to the end of the menu.
  39059.  
  39060. The string passed to AppendMenu consists mainly of the text of the menu items. For a
  39061. dividing line, use one hyphen (–); AppendMenu ignores any following characters, and
  39062. draws a dotted line across the width of the menu. For a blank item, use one or more
  39063. spaces. Other characters interspersed in the string have special meaning to the Menu
  39064. Manager. These “meta-characters” are used in conjunction with text to separate menu
  39065. items or alter their appearance (for example, you can use one to disable any dividing
  39066. line or blank item). The
  39067. meta-characters aren’t displayed in the menu.
  39068.  
  39069.   Meta-character    Meaning
  39070.  
  39071.   ; or Return       Separates items
  39072.   ^                 Item has an icon
  39073.   !                 Item has a check or other mark
  39074.   <                 Item has a special character style
  39075.   /                 Item has a keyboard equivalent
  39076.   (                 Item is disabled
  39077.  
  39078. None, any, or all of these meta-characters can appear in the AppendMenu string;
  39079. they’re described in detail below. To add one text-only item to a menu would require
  39080. a simple string without any meta-characters:
  39081.  
  39082.   AppendMenu(thisMenu,'Just Enough')
  39083.  
  39084. An extreme example could use many meta-characters:
  39085.  
  39086.   AppendMenu(thisMenu,'(Too Much^1<B/T')
  39087.  
  39088. This example adds to the menu an item whose text is “Too Much”, which is disabled,
  39089. has icon number 1, is boldfaced, and can be invoked by Command-T. Your menu items
  39090. should be much simpler than this.
  39091.  
  39092. Note:  If you want any of the meta-characters to appear in the text of a
  39093.        menu item, you can include them by changing the text with the Menu
  39094.        Manager procedure SetItem.
  39095.  
  39096. _______________________________________________________________________________
  39097.  
  39098. »Multiple Items
  39099.  
  39100. Each call to AppendMenu can add one or many items to the menu. To add multiple items
  39101. in the same call, use a semicolon (;) or a Return character to separate the items.
  39102. The call
  39103.  
  39104.   AppendMenu(thisMenu,'Cut;Copy')
  39105.  
  39106. has exactly the same effect as the calls
  39107.  
  39108.   AppendMenu(thisMenu,'Cut');
  39109.   AppendMenu(thisMenu,'Copy')
  39110.  
  39111. _______________________________________________________________________________
  39112.  
  39113. »Items with Icons
  39114.  
  39115. A circumflex (^ ) followed by a digit from 1 to 9 indicates that an icon should
  39116. appear to the left of the text in the menu. The digit, called the icon number, yields
  39117. the resource ID of the icon in the resource file. Icon resource IDs 257 through 511
  39118. are reserved for menu icons; thus the Menu Manager adds 256 to the icon number to get
  39119. the proper resource ID.
  39120.  
  39121. Note:  The Menu Manager gets the icon number by subtracting 48 from the ASCII
  39122.        code of the character following the “^” (since, for example, the ASCII
  39123.        code of “1” is 49). You can actually follow the “^” with any character
  39124.        that has an ASCII code greater than 48.
  39125.  
  39126. You can also use the SetItemIcon procedure to install icons in a menu; it accepts any
  39127. icon number from 1 to 255.
  39128.  
  39129. _______________________________________________________________________________
  39130.  
  39131. »Marked Items
  39132.  
  39133. You can use an exclamation point (!) to cause a check mark or any other character to
  39134. be placed to the left of the text (or icon, if any). Follow the exclamation point
  39135. with the character of your choice; note, however, that normally you can’t type a
  39136. check mark from the keyboard. To specify a check mark, you need to take special
  39137. measures:  Declare a string variable to have the length of the desired AppendMenu
  39138. string, and assign it that string with a space following the exclamation point. Then
  39139. separately store the check mark in the position of the space.
  39140.  
  39141. For example, suppose you want to use AppendMenu to specify a menu item that has the
  39142. text “Word Wraparound” (15 characters) and a check mark to its left. You can declare
  39143. the string variable
  39144.  
  39145.   VAR s:  STRING[17];
  39146.  
  39147. and do the following:
  39148.  
  39149.   s := '! Word Wraparound';
  39150.   s[2] := CHR(checkMark);
  39151.   AppendMenu(thisMenu,s)
  39152.  
  39153. The constant checkMark is defined by the Font Manager as the character code for the
  39154. check mark.
  39155.  
  39156. Note:  The Font Manager also defines constants for certain other special
  39157.        characters that can’t normally be typed from the keyboard:  the apple
  39158.        symbol, the Command key symbol, and a diamond symbol. These symbols
  39159.        can be specified in the same way as the check mark.
  39160.  
  39161. You can call the SetItemMark or CheckItem procedures to change or clear the mark, and
  39162. the GetItemMark procedure to find out what mark, if any, is being used.
  39163.  
  39164. _______________________________________________________________________________
  39165.  
  39166. »Character Style of Items
  39167.  
  39168. The system font is the only font available for menus; however, you can vary the
  39169. character style of menu items for clarity and distinction. The meta-character for
  39170. specifying the character style of an item’s text is the less-than symbol
  39171. (<). With AppendMenu, you can assign one and only one of the stylistic variations
  39172. listed below.
  39173.  
  39174.   <B    Bold
  39175.   <I    Italic
  39176.   <U    Underline
  39177.   <O    Outline
  39178.   <S    Shadow
  39179.  
  39180. The SetItemStyle procedure allows you to assign any combination of stylistic variations
  39181. to an item. For a further discussion of character style, see the QuickDraw chapter.
  39182.  
  39183. _______________________________________________________________________________
  39184.  
  39185. »Items with Keyboard Equivalents
  39186.  
  39187. A slash (/) followed by a character associates that character with the item, allowing
  39188. the item to be invoked from the keyboard with the Command key. The specified character
  39189. (preceded by the Command key symbol) appears at the right of the item’s text in the
  39190. menu.
  39191.  
  39192. Note:  Remember to specify the character in uppercase if it’s a letter, and
  39193.        not to specify other shifted characters or numbers.
  39194.  
  39195. Given a keyboard equivalent typed by the user, you call the MenuKey function to find
  39196. out which menu item was invoked.
  39197.  
  39198. _______________________________________________________________________________
  39199.  
  39200. »Disabled Items
  39201.  
  39202. The meta-character that disables an item is the left parenthesis, “(”. A disabled
  39203. item cannot be chosen; it appears dimmed in the menu and is not highlighted when the
  39204. cursor moves over it.
  39205.  
  39206. Menu items that are used to separate groups of items (such as a line or a blank item)
  39207. should always be disabled. For example, the call
  39208.  
  39209.   AppendMenu(thisMenu,'Undo;(-;Cut')
  39210.  
  39211. adds two enabled menu items, Undo and Cut, with a disabled item consisting of a line
  39212. between them.
  39213.  
  39214. You can change the enabled or disabled state of a menu item with the DisableItem and
  39215. EnableItem procedures.
  39216.  
  39217. æKY insmenuitem
  39218. æFc Menus.h
  39219. æT Function
  39220. æD void insmenuitem(MenuHandle theMenu,char *itemString,short afterItem); 
  39221. æDT insmenuitem((MenuHandle) theMenu,(char *) itemString,(short) afterItem);
  39222. æMM
  39223. æRI IV-55
  39224. æC 
  39225. InsMenuItem inserts an item or items into the given menu where specified by the
  39226. afterItem parameter. If afterItem is 0, the items are inserted before the first menu
  39227. item; if it’s the item number of an item in the menu, they’re inserted after that
  39228. item; if it’s equal to or greater than the last item number, they’re appended to the
  39229. menu.
  39230.  
  39231. The contents of itemString are parsed as in the AppendMenu procedure. Multiple items
  39232. are inserted in the reverse of their order in itemString.
  39233.  
  39234. æKY menuselect
  39235. æFc Menus.h
  39236. æT Function
  39237. æD long menuselect(Point *startPt); 
  39238. æDT long myVariable = menuselect((Point *) startPt);
  39239. æMM
  39240. æRI I-355, V-244, P-36, 103, 105, 176
  39241. æC 
  39242. When there’s a mouse-down event in the menu bar, the application should call MenuSelect
  39243. with startPt equal to the point (in global coordinates) where the mouse button was
  39244. pressed. MenuSelect keeps control until the mouse button is released, tracking the
  39245. mouse, pulling down menus as needed, and highlighting enabled menu items under the
  39246. cursor. When the mouse button is released over an enabled item in an application
  39247. menu, MenuSelect returns a long integer whose high-order word is the menu ID of the
  39248. menu, and whose low-order word is the menu item number for the item chosen (see
  39249. Figure 4). It leaves the selected menu title highlighted. After performing the chosen
  39250. task, your application should call HiliteMenu(0) to remove the highlighting from the
  39251. menu title.
  39252.  
  39253. If no choice is made, MenuSelect returns 0 in the high-order word of the long integer,
  39254. and the low-order word is undefined. This includes the case where the mouse button is
  39255. released over a disabled menu item (such as Cut, Copy, Clear, or one of the dividing
  39256. lines in Figure 4), over any menu title, or outside the menu.  In the case of a
  39257. disabled menu item, an application can still determine which item was chosen.  See
  39258. the description of the MenuChoice routine for further details.
  39259.  
  39260. If the mouse button is released over an enabled item in a menu belonging to a desk
  39261. accessory, MenuSelect passes the menu ID and item number to the Desk Manager procedure
  39262. SystemMenu for processing, and returns 0 to your application in the high-order word
  39263. of the result.
  39264.  
  39265. Note:  When a menu is pulled down, the bits behind it are stored as a
  39266.        relocatable object in the application heap. If your application
  39267.        has large menus, this can temporarily use up a lot of memory.
  39268.  
  39269. •••Refer to Figure 4.•••
  39270.  
  39271. Figure 4–MenuSelect and MenuKey
  39272.  
  39273. Assembly-language note:  If the global variable MBarEnable is nonzero,
  39274.                          MenuSelect knows that every menu currently in
  39275.                          the menu bar belongs to a desk accessory. (See
  39276.                          the Desk Manager chapter for more information.)
  39277.  
  39278.                          You can store in the global variables MenuHook and
  39279.                          MBarHook the addresses of routines that will be called
  39280.                          during MenuSelect. Both variables are initialized to
  39281.                          0 by InitMenus. The routine whose address is in
  39282.                          MenuHook (if any) will be called repeatedly (with no
  39283.                          parameters) while the mouse button is down. The
  39284.                          routine whose address is in MBarHook (if any) will
  39285.                          be called after the title of the menu is highlighted
  39286.                          and the menu rectangle is calculated, but before the
  39287.                          menu is drawn. (The menu rectangle is the rectangle in
  39288.                          which the menu will be drawn, in global coordinates.)
  39289.                          The routine is passed a pointer to the menu rectangle
  39290.                          on the stack. It should normally return 0 in register
  39291.                          D0; returning 1 will abort MenuSelect.
  39292.  
  39293. If the user chooses an item with a submenu, MenuSelect returns zero, meaning that no
  39294. item was selected. If the user selects an item from a hierarchical menu, the menuID
  39295. of the hierarchical menu and the menuItem of the item chosen are returned, just as
  39296. though the item had been in a regular menu.
  39297.  
  39298. If MenuSelect returns zero, an application may call MenuChoice to determine whether
  39299. the mouse was released over either a disabled menu item or an item with a submenu.
  39300.  
  39301. Note:  The global variable TheMenu contains the ID of the highlighted menu in
  39302.        the menu bar. If an item from a hierarchical menu is chosen, TheMenu
  39303.        contains the ID of the “owner” menu, not the ID of the hierarchical menu.
  39304.  
  39305. æKY setitem
  39306. æFc Menus.h
  39307. æT Function
  39308. æD void setitem(MenuHandle menu,short item,char *itemString); 
  39309. æDT setitem((MenuHandle) menu,(short) item,(char *) itemString);
  39310. æMM
  39311. æRI I-357, P-104, 180
  39312. æC 
  39313. SetItem changes the text of the given menu item to itemString. It doesn’t recognize
  39314. the meta-characters used in AppendMenu; if you include them in itemString, they will
  39315. appear in the text of the menu item. The attributes already in effect for this item—its
  39316. character style, icon, and so on—remain in effect. ItemString may be blank but should
  39317. not be the empty string.
  39318.  
  39319. Note:  It’s good practice to store the text of itemString in a resource
  39320.        file instead of passing it directly.
  39321.  
  39322. Use SetItem to change between the two forms of a toggled command—for example, to
  39323. change “Show Clipboard” to “Hide Clipboard” when the Clipboard is already showing.
  39324.  
  39325. Note:  To avoid confusing the user, don’t capriciously change the text
  39326.        of menu items.
  39327.  
  39328.  
  39329. æKY MIDI.h
  39330. æKL MIDIAddPort
  39331. MIDIConnectData
  39332. MIDIConnectTime
  39333. MIDIConvertTime
  39334. MIDIFlush
  39335. MIDIGetClientIcon
  39336. MIDIGetClientName
  39337. MIDIGetClients
  39338. MIDIGetClRefCon
  39339. MIDIGetCurTime
  39340. MIDIGetOffsetTime
  39341. MIDIGetPortInfo
  39342. MIDIGetPortName
  39343. MIDIGetPorts
  39344. MIDIGetReadHook
  39345. MIDIGetRefCon
  39346. MIDIGetSync
  39347. MIDIGetTCFormat
  39348. MIDIPoll
  39349. MIDIRemovePort
  39350. MIDISetClientName
  39351. MIDISetClRefCon
  39352. MIDISetCurTime
  39353. MIDISetOffsetTime
  39354. MIDISetPortName
  39355. MIDISetReadHook
  39356. MIDISetRefCon
  39357. MIDISetRunRate
  39358. MIDISetSync
  39359. MIDISetTCFormat
  39360. MIDISignIn
  39361. MIDISignOut
  39362. MIDIStartTime
  39363. MIDIStopTime
  39364. MIDIUnConnectData
  39365. MIDIUnConnectTime
  39366. MIDIWakeUp
  39367. MIDIWorldChanged
  39368. MIDIWritePacket
  39369. SndDispVersion
  39370.  
  39371. MIDIClkInfo
  39372. midiCloseDriver
  39373. midiContMask
  39374. midiDupIDErr
  39375. midiEndCont
  39376. midiExternalSync
  39377. midiFormat24fpsBit
  39378. midiFormat24fpsQF
  39379. midiFormat25fpsBit
  39380. midiFormat25fpsQF
  39381. midiFormat30fpsBit
  39382. midiFormat30fpsDBit
  39383. midiFormat30fpsDQF
  39384. midiFormat30fpsQF
  39385. midiFormatBeats
  39386. midiFormatMSec
  39387. midiGetCurrent
  39388. midiGetEverything
  39389. midiGetNothing
  39390. MIDIIDList
  39391. MIDIIDListHdl
  39392. MIDIIDListPtr
  39393. MIDIIDRec
  39394. midiInternalSync
  39395. midiInvalidCmdErr
  39396. midiKeepPacket
  39397. midiMaxErr
  39398. midiMaxNameLen
  39399. midiMgrType
  39400. midiMidCont
  39401. midiMorePacket
  39402. midiMsgType
  39403. midiNameLenErr
  39404. midiNoClientErr
  39405. midiNoConErr
  39406. midiNoCont
  39407. midiNoMorePacket
  39408. midiNoPortErr
  39409. midiOpenDriver
  39410. midiOverflowErr
  39411. MIDIPacket
  39412. midiPacketErr
  39413. MIDIPacketPtr
  39414. MIDIPortInfo
  39415. MIDIPortInfoHdl
  39416. MIDIPortInfoPtr
  39417. MIDIPortParams
  39418. MIDIPortParamsPtr
  39419. midiPortTypeInput
  39420. midiPortTypeOutput
  39421. midiPortTypeTime
  39422. midiPortTypeTimeInv
  39423. midiSCCErr
  39424. midiStartCont
  39425. midiTimeStampCurrent
  39426. midiTimeStampMask
  39427. midiTimeStampValid
  39428. midiToolNum
  39429. midiTooManyConsErr
  39430. midiTooManyPortsErr
  39431. midiTypeMask
  39432. midiVConnectErr
  39433. midiVConnectMade
  39434. midiVConnectRmvd
  39435. midiWriteErr
  39436.  
  39437. æKY midiToolNum
  39438. æFc MIDI.h
  39439. æT #define
  39440. æD #define midiToolNum 4 /*tool number of MIDI Manager for SndDispVersion call*/
  39441. æC 
  39442.  
  39443. æKY midiMaxNameLen
  39444. æFc MIDI.h
  39445. æT #define
  39446. æD #define midiMaxNameLen 31 /*maximum number of characters in port and client names*/
  39447. æC 
  39448.  
  39449. æKY midiFormatMSec
  39450. æFc MIDI.h
  39451. æT #define
  39452. æD 
  39453. /* Time formats */
  39454.  
  39455. #define midiFormatMSec 0 /*milliseconds*/
  39456. æC 
  39457.  
  39458. æKY midiFormatBeats
  39459. æFc MIDI.h
  39460. æT #define
  39461. æD #define midiFormatBeats 1 /*beats*/
  39462. æC 
  39463.  
  39464. æKY midiFormat24fpsBit
  39465. æFc MIDI.h
  39466. æT #define
  39467. æD #define midiFormat24fpsBit 2 /*24 frames/sec.*/
  39468. æC 
  39469.  
  39470. æKY midiFormat25fpsBit
  39471. æFc MIDI.h
  39472. æT #define
  39473. æD #define midiFormat25fpsBit 3 /*25 frames/sec.*/
  39474. æC 
  39475.  
  39476. æKY midiFormat30fpsDBit
  39477. æFc MIDI.h
  39478. æT #define
  39479. æD #define midiFormat30fpsDBit 4 /*30 frames/sec. drop-frame*/
  39480. æC 
  39481.  
  39482. æKY midiFormat30fpsBit
  39483. æFc MIDI.h
  39484. æT #define
  39485. æD #define midiFormat30fpsBit 5 /*30 frames/sec.*/
  39486. æC 
  39487.  
  39488. æKY midiFormat24fpsQF
  39489. æFc MIDI.h
  39490. æT #define
  39491. æD #define midiFormat24fpsQF 6 /*24 frames/sec. longInt format */
  39492. æC 
  39493.  
  39494. æKY midiFormat25fpsQF
  39495. æFc MIDI.h
  39496. æT #define
  39497. æD #define midiFormat25fpsQF 7 /*25 frames/sec. longInt format */
  39498. æC 
  39499.  
  39500. æKY midiFormat30fpsDQF
  39501. æFc MIDI.h
  39502. æT #define
  39503. æD #define midiFormat30fpsDQF 8 /*30 frames/sec. drop-frame longInt format */
  39504. æC 
  39505.  
  39506. æKY midiFormat30fpsQF
  39507. æFc MIDI.h
  39508. æT #define
  39509. æD #define midiFormat30fpsQF 9 /*30 frames/sec. longInt format */
  39510. æC 
  39511.  
  39512. æKY midiInternalSync
  39513. æFc MIDI.h
  39514. æT #define
  39515. æD #define midiInternalSync 0 /*internal sync*/
  39516. æC 
  39517.  
  39518. æKY midiExternalSync
  39519. æFc MIDI.h
  39520. æT #define
  39521. æD #define midiExternalSync 1 /*external sync*/
  39522. æC 
  39523.  
  39524. æKY midiPortTypeTime
  39525. æFc MIDI.h
  39526. æT #define
  39527. æD 
  39528. /*  Port types */
  39529.  
  39530. #define midiPortTypeTime 0 /*time port*/
  39531. æC 
  39532.  
  39533. æKY midiPortTypeInput
  39534. æFc MIDI.h
  39535. æT #define
  39536. æD #define midiPortTypeInput 1 /*input port*/
  39537. æC 
  39538.  
  39539. æKY midiPortTypeOutput
  39540. æFc MIDI.h
  39541. æT #define
  39542. æD #define midiPortTypeOutput 2 /*output port*/
  39543. æC 
  39544.  
  39545. æKY midiPortTypeTimeInv
  39546. æFc MIDI.h
  39547. æT #define
  39548. æD #define midiPortTypeTimeInv 3 /*invisible time port*/
  39549. æC 
  39550.  
  39551. æKY midiGetEverything
  39552. æFc MIDI.h
  39553. æT #define
  39554. æD 
  39555. /* OffsetTimes  */
  39556.  
  39557. #define midiGetEverything 0x7FFFFFFF /*get all packets, regardless of time stamps*/
  39558. æC 
  39559.  
  39560. æKY midiGetNothing
  39561. æFc MIDI.h
  39562. æT #define
  39563. æD #define midiGetNothing 0x80000000 /*get no packets, regardless of time stamps*/
  39564. æC 
  39565.  
  39566. æKY midiGetCurrent
  39567. æFc MIDI.h
  39568. æT #define
  39569. æD #define midiGetCurrent 0x00000000 /*get current packets only*/
  39570. æC 
  39571.  
  39572. æKY midiContMask
  39573. æFc MIDI.h
  39574. æT #define
  39575. æD 
  39576. /*     MIDI data and messages are passed in MIDIPacket records (see below).
  39577.     The first byte of every MIDIPacket contains a set of flags
  39578.    
  39579.     bits 0-1    00 = new MIDIPacket, not continued
  39580.                      01 = begining of continued MIDIPacket
  39581.                      10 = end of continued MIDIPacket
  39582.                     11 = continuation
  39583.     bits 2-3     reserved
  39584.   
  39585.     bits 4-6      000 = packet contains MIDI data
  39586.    
  39587.                      001 = packet contains MIDI Manager message
  39588.    
  39589.     bit 7              0 = MIDIPacket has valid stamp
  39590.                         1 = stamp with current clock */
  39591.  
  39592. #define midiContMask 0x03
  39593. æC 
  39594.  
  39595. æKY midiNoCont
  39596. æFc MIDI.h
  39597. æT #define
  39598. æD #define midiNoCont 0x00
  39599. æC 
  39600.  
  39601. æKY midiStartCont
  39602. æFc MIDI.h
  39603. æT #define
  39604. æD #define midiStartCont 0x01
  39605. æC 
  39606.  
  39607. æKY midiMidCont
  39608. æFc MIDI.h
  39609. æT #define
  39610. æD #define midiMidCont 0x03
  39611. æC 
  39612.  
  39613. æKY midiEndCont
  39614. æFc MIDI.h
  39615. æT #define
  39616. æD #define midiEndCont 0x02
  39617. æC 
  39618.  
  39619. æKY midiTypeMask
  39620. æFc MIDI.h
  39621. æT #define
  39622. æD #define midiTypeMask 0x70
  39623. æC 
  39624.  
  39625. æKY midiMsgType
  39626. æFc MIDI.h
  39627. æT #define
  39628. æD #define midiMsgType 0x00
  39629. æC 
  39630.  
  39631. æKY midiMgrType
  39632. æFc MIDI.h
  39633. æT #define
  39634. æD #define midiMgrType 0x10
  39635. æC 
  39636.  
  39637. æKY midiTimeStampMask
  39638. æFc MIDI.h
  39639. æT #define
  39640. æD #define midiTimeStampMask 0x80
  39641. æC 
  39642.  
  39643. æKY midiTimeStampCurrent
  39644. æFc MIDI.h
  39645. æT #define
  39646. æD #define midiTimeStampCurrent 0x80
  39647. æC 
  39648.  
  39649. æKY midiTimeStampValid
  39650. æFc MIDI.h
  39651. æT #define
  39652. æD #define midiTimeStampValid 0x00
  39653. æC 
  39654.  
  39655. æKY midiOverflowErr
  39656. æFc MIDI.h
  39657. æT #define
  39658. æD 
  39659. /*     MIDI Manager MIDIPacket command words (the first word in the data field
  39660.     for midiMgrType messages) */
  39661.  
  39662. #define midiOverflowErr 0x0001
  39663. æC 
  39664.  
  39665. æKY midiSCCErr
  39666. æFc MIDI.h
  39667. æT #define
  39668. æD #define midiSCCErr 0x0002
  39669. æC 
  39670.  
  39671. æKY midiPacketErr
  39672. æFc MIDI.h
  39673. æT #define
  39674. æD #define midiPacketErr 0x0003
  39675. æC 
  39676.  
  39677. æKY midiMaxErr
  39678. æFc MIDI.h
  39679. æT #define
  39680. æD #define midiMaxErr 0x00FF /*all command words less than this value  are error indicators*/
  39681. æC 
  39682.  
  39683. æKY midiKeepPacket
  39684. æFc MIDI.h
  39685. æT #define
  39686. æD 
  39687. /* Valid results to be returned by readHooks  */
  39688.  
  39689. #define midiKeepPacket 0
  39690. æC 
  39691.  
  39692. æKY midiMorePacket
  39693. æFc MIDI.h
  39694. æT #define
  39695. æD #define midiMorePacket 1
  39696. æC 
  39697.  
  39698. æKY midiNoMorePacket
  39699. æFc MIDI.h
  39700. æT #define
  39701. æD #define midiNoMorePacket 2
  39702. æC 
  39703.  
  39704. æKY midiNoClientErr
  39705. æFc MIDI.h
  39706. æT #define
  39707. æD 
  39708. /*  Errors: */
  39709.  
  39710. #define midiNoClientErr -250 /*no client with that ID found*/
  39711. æC 
  39712.  
  39713. æKY midiNoPortErr
  39714. æFc MIDI.h
  39715. æT #define
  39716. æD #define midiNoPortErr -251 /*no port with that ID found*/
  39717. æC 
  39718.  
  39719. æKY midiTooManyPortsErr
  39720. æFc MIDI.h
  39721. æT #define
  39722. æD #define midiTooManyPortsErr -252 /*too many ports already installed in the system*/
  39723. æC 
  39724.  
  39725. æKY midiTooManyConsErr
  39726. æFc MIDI.h
  39727. æT #define
  39728. æD #define midiTooManyConsErr -253 /*too many connections made*/
  39729. æC 
  39730.  
  39731. æKY midiVConnectErr
  39732. æFc MIDI.h
  39733. æT #define
  39734. æD #define midiVConnectErr -254 /*pending virtual connection created*/
  39735. æC 
  39736.  
  39737. æKY midiVConnectMade
  39738. æFc MIDI.h
  39739. æT #define
  39740. æD #define midiVConnectMade -255 /*pending virtual connection resolved*/
  39741. æC 
  39742.  
  39743. æKY midiVConnectRmvd
  39744. æFc MIDI.h
  39745. æT #define
  39746. æD #define midiVConnectRmvd -256 /*pending virtual connection removed*/
  39747. æC 
  39748.  
  39749. æKY midiNoConErr
  39750. æFc MIDI.h
  39751. æT #define
  39752. æD #define midiNoConErr -257 /*no connection exists between specified ports*/
  39753. æC 
  39754.  
  39755. æKY midiWriteErr
  39756. æFc MIDI.h
  39757. æT #define
  39758. æD #define midiWriteErr -258 /*MIDIWritePacket couldn't write to all connected ports*/
  39759. æC 
  39760.  
  39761. æKY midiNameLenErr
  39762. æFc MIDI.h
  39763. æT #define
  39764. æD #define midiNameLenErr -259 /*name supplied is longer than 31 characters*/
  39765. æC 
  39766.  
  39767. æKY midiDupIDErr
  39768. æFc MIDI.h
  39769. æT #define
  39770. æD #define midiDupIDErr -260 /*duplicate client ID*/
  39771. æC 
  39772.  
  39773. æKY midiInvalidCmdErr
  39774. æFc MIDI.h
  39775. æT #define
  39776. æD #define midiInvalidCmdErr -261 /*command not supported for port type*/
  39777. æC 
  39778.  
  39779. æKY midiOpenDriver
  39780. æFc MIDI.h
  39781. æT #define
  39782. æD 
  39783. /*      Driver calls: */
  39784.  
  39785. #define midiOpenDriver 1
  39786. æC 
  39787.  
  39788. æKY midiCloseDriver
  39789. æFc MIDI.h
  39790. æT #define
  39791. æD #define midiCloseDriver 2
  39792. æC 
  39793.  
  39794. æKY MIDIPacket
  39795. MIDIPacketPtr
  39796. æFc MIDI.h
  39797. æT struct
  39798. æD struct MIDIPacket {
  39799.     unsigned char flags;
  39800.     unsigned char len;
  39801.     long tStamp;
  39802.     unsigned char data[249];
  39803. };
  39804.  
  39805. typedef struct MIDIPacket MIDIPacket;
  39806. typedef MIDIPacket *MIDIPacketPtr;
  39807.  
  39808. æC 
  39809.  
  39810. æKY MIDIClkInfo
  39811. æFc MIDI.h
  39812. æT struct
  39813. æD struct MIDIClkInfo {
  39814.     short sync; /*synchronization external/internal*/
  39815.     long curTime; /*current value of port's clock*/
  39816.     short format; /*time code format*/
  39817. };
  39818.  
  39819. typedef struct MIDIClkInfo MIDIClkInfo;
  39820. æC 
  39821.  
  39822. æKY MIDIIDRec
  39823. æFc MIDI.h
  39824. æT struct
  39825. æD struct MIDIIDRec {
  39826.     OSType clientID;
  39827.     OSType portID;
  39828. };
  39829.  
  39830. typedef struct MIDIIDRec MIDIIDRec;
  39831. æC 
  39832.  
  39833. æKY MIDIPortInfo
  39834. MIDIPortInfoPtr
  39835. MIDIPortInfoHdl
  39836. æFc MIDI.h
  39837. æT struct
  39838. æD struct MIDIPortInfo {
  39839.     short portType; /*type of port*/
  39840.     MIDIIDRec timeBase; /*MIDIIDRec for time base*/
  39841.     short numConnects; /*number of connections*/
  39842.     MIDIIDRec cList[1]; /*ARRAY [1..numConnects] of MIDIIDRec*/
  39843. };
  39844.  
  39845. typedef struct MIDIPortInfo MIDIPortInfo;
  39846. typedef MIDIPortInfo *MIDIPortInfoPtr, **MIDIPortInfoHdl;
  39847.  
  39848. æC 
  39849.  
  39850. æKY MIDIPortParams
  39851. MIDIPortParamsPtr
  39852. æFc MIDI.h
  39853. æT struct
  39854. æD struct MIDIPortParams {
  39855.     OSType portID; /*ID of port, unique within client*/
  39856.     short portType; /*Type of port - input, output, time, etc.*/
  39857.     short timeBase; /*refnum of time base, 0 if none*/
  39858.     long offsetTime; /*offset for current time stamps*/
  39859.     Ptr readHook; /*routine to call when input data is valid*/
  39860.     long refCon; /*refcon for port (for client use)*/
  39861.     MIDIClkInfo initClock; /*initial settings for a time base*/
  39862.     Str255 name; /*name of the port, This is a real live string, not a ptr.*/
  39863. };
  39864.  
  39865. typedef struct MIDIPortParams MIDIPortParams;
  39866. typedef MIDIPortParams *MIDIPortParamsPtr;
  39867.  
  39868. æC 
  39869.  
  39870. æKY MIDIIDList
  39871. MIDIIDListPtr
  39872. MIDIIDListHdl
  39873. æFc MIDI.h
  39874. æT struct
  39875. æD struct MIDIIDList {
  39876.     short numIDs;
  39877.     OSType list[1];
  39878. };
  39879.  
  39880. typedef struct MIDIIDList MIDIIDList;
  39881. typedef MIDIIDList *MIDIIDListPtr, **MIDIIDListHdl;
  39882.  
  39883. æC 
  39884.  
  39885. æKY SndDispVersion
  39886. æFc MIDI.h
  39887. æT Function
  39888. æD pascal long SndDispVersion(short toolnum); 
  39889. æDT long myVariable = SndDispVersion((short) toolnum);
  39890. æC 
  39891.  
  39892. æKY MIDISignIn
  39893. æFc MIDI.h
  39894. æT Function
  39895. æD pascal OSErr MIDISignIn(OSType clientID,long refCon,Handle icon,const Str255 name)
  39896.     = {0x203C,0x0004,midiToolNum,0xA800}; 
  39897. æDT OSErr myVariable = MIDISignIn((OSType) clientID,(long) refCon,(Handle) icon,(const Str255) name);
  39898. æC 
  39899.  
  39900. æKY MIDISignOut
  39901. æFc MIDI.h
  39902. æT Function
  39903. æD pascal void MIDISignOut(OSType clientID)
  39904.     = {0x203C,0x0008,midiToolNum,0xA800}; 
  39905. æDT MIDISignOut((OSType) clientID);
  39906. æC 
  39907.  
  39908. æKY MIDIGetClients
  39909. æFc MIDI.h
  39910. æT Function
  39911. æD pascal MIDIIDListHdl MIDIGetClients(void)
  39912.     = {0x203C,0x000C,midiToolNum,0xA800}; 
  39913. æDT MIDIIDListHdl myVariable = MIDIGetClients()(void);
  39914. æC 
  39915.  
  39916. æKY MIDIGetClientName
  39917. æFc MIDI.h
  39918. æT Function
  39919. æD pascal void MIDIGetClientName(OSType clientID,const Str255 name)
  39920.     = {0x203C,0x0010,midiToolNum,0xA800}; 
  39921. æDT MIDIGetClientName((OSType) clientID,(const Str255) name);
  39922. æC 
  39923.  
  39924. æKY MIDISetClientName
  39925. æFc MIDI.h
  39926. æT Function
  39927. æD pascal void MIDISetClientName(OSType clientID,const Str255 name)
  39928.     = {0x203C,0x0014,midiToolNum,0xA800}; 
  39929. æDT MIDISetClientName((OSType) clientID,(const Str255) name);
  39930. æC 
  39931.  
  39932. æKY MIDIGetPorts
  39933. æFc MIDI.h
  39934. æT Function
  39935. æD pascal MIDIIDListHdl MIDIGetPorts(OSType clientID)
  39936.     = {0x203C,0x0018,midiToolNum,0xA800}; 
  39937. æDT MIDIIDListHdl myVariable = MIDIGetPorts((OSType) clientID);
  39938. æC 
  39939.  
  39940. æKY MIDIAddPort
  39941. æFc MIDI.h
  39942. æT Function
  39943. æD pascal OSErr MIDIAddPort(OSType clientID,short BufSize,short *refnum,MIDIPortParamsPtr init)
  39944.     = {0x203C,0x001C,midiToolNum,0xA800}; 
  39945. æDT OSErr myVariable = MIDIAddPort((OSType) clientID,(short) BufSize,(short *) refnum,(MIDIPortParamsPtr) init);
  39946. æC 
  39947.  
  39948. æKY MIDIGetPortInfo
  39949. æFc MIDI.h
  39950. æT Function
  39951. æD pascal MIDIPortInfoHdl MIDIGetPortInfo(OSType clientID,OSType portID)
  39952.     = {0x203C,0x0020,midiToolNum,0xA800}; 
  39953. æDT MIDIPortInfoHdl myVariable = MIDIGetPortInfo((OSType) clientID,(OSType) portID);
  39954. æC 
  39955.  
  39956. æKY MIDIConnectData
  39957. æFc MIDI.h
  39958. æT Function
  39959. æD pascal OSErr MIDIConnectData(OSType srcClID,OSType srcPortID,OSType dstClID,
  39960.     OSType dstPortID)
  39961.     = {0x203C,0x0024,midiToolNum,0xA800}; 
  39962. æDT OSErr myVariable = MIDIConnectData((OSType) srcClID,(OSType) srcPortID,(OSType) dstClID,()
  39963.     OSType dstPortID);
  39964. æC 
  39965.  
  39966. æKY MIDIUnConnectData
  39967. æFc MIDI.h
  39968. æT Function
  39969. æD pascal OSErr MIDIUnConnectData(OSType srcClID,OSType srcPortID,OSType dstClID,
  39970.     OSType dstPortID)
  39971.     = {0x203C,0x0028,midiToolNum,0xA800}; 
  39972. æDT OSErr myVariable = MIDIUnConnectData((OSType) srcClID,(OSType) srcPortID,(OSType) dstClID,()
  39973.     OSType dstPortID);
  39974. æC 
  39975.  
  39976. æKY MIDIConnectTime
  39977. æFc MIDI.h
  39978. æT Function
  39979. æD pascal OSErr MIDIConnectTime(OSType srcClID,OSType srcPortID,OSType dstClID,
  39980.     OSType dstPortID)
  39981.     = {0x203C,0x002C,midiToolNum,0xA800}; 
  39982. æDT OSErr myVariable = MIDIConnectTime((OSType) srcClID,(OSType) srcPortID,(OSType) dstClID,()
  39983.     OSType dstPortID);
  39984. æC 
  39985.  
  39986. æKY MIDIUnConnectTime
  39987. æFc MIDI.h
  39988. æT Function
  39989. æD pascal OSErr MIDIUnConnectTime(OSType srcClID,OSType srcPortID,OSType dstClID,
  39990.     OSType dstPortID)
  39991.     = {0x203C,0x0030,midiToolNum,0xA800}; 
  39992. æDT OSErr myVariable = MIDIUnConnectTime((OSType) srcClID,(OSType) srcPortID,(OSType) dstClID,()
  39993.     OSType dstPortID);
  39994. æC 
  39995.  
  39996. æKY MIDIFlush
  39997. æFc MIDI.h
  39998. æT Function
  39999. æD pascal void MIDIFlush(short refnum)
  40000.     = {0x203C,0x0034,midiToolNum,0xA800}; 
  40001. æDT MIDIFlush((short) refnum);
  40002. æC 
  40003.  
  40004. æKY MIDIGetReadHook
  40005. æFc MIDI.h
  40006. æT Function
  40007. æD pascal ProcPtr MIDIGetReadHook(short refnum)
  40008.     = {0x203C,0x0038,midiToolNum,0xA800}; 
  40009. æDT ProcPtr myVariable = MIDIGetReadHook((short) refnum);
  40010. æC 
  40011.  
  40012. æKY MIDISetReadHook
  40013. æFc MIDI.h
  40014. æT Function
  40015. æD pascal void MIDISetReadHook(short refnum,ProcPtr hook)
  40016.     = {0x203C,0x003C,midiToolNum,0xA800}; 
  40017. æDT MIDISetReadHook((short) refnum,(ProcPtr) hook);
  40018. æC 
  40019.  
  40020. æKY MIDIGetPortName
  40021. æFc MIDI.h
  40022. æT Function
  40023. æD pascal void MIDIGetPortName(OSType clientID,OSType portID,const Str255 name)
  40024.     = {0x203C,0x0040,midiToolNum,0xA800}; 
  40025. æDT MIDIGetPortName((OSType) clientID,(OSType) portID,(const Str255) name);
  40026. æC 
  40027.  
  40028. æKY MIDISetPortName
  40029. æFc MIDI.h
  40030. æT Function
  40031. æD pascal void MIDISetPortName(OSType clientID,OSType portID,const Str255 name)
  40032.     = {0x203C,0x0044,midiToolNum,0xA800}; 
  40033. æDT MIDISetPortName((OSType) clientID,(OSType) portID,(const Str255) name);
  40034. æC 
  40035.  
  40036. æKY MIDIWakeUp
  40037. æFc MIDI.h
  40038. æT Function
  40039. æD pascal void MIDIWakeUp(short refnum,long time,long period,ProcPtr timeProc)
  40040.     = {0x203C,0x0048,midiToolNum,0xA800}; 
  40041. æDT MIDIWakeUp((short) refnum,(long) time,(long) period,(ProcPtr) timeProc);
  40042. æC 
  40043.  
  40044. æKY MIDIRemovePort
  40045. æFc MIDI.h
  40046. æT Function
  40047. æD pascal void MIDIRemovePort(short refnum)
  40048.     = {0x203C,0x004C,midiToolNum,0xA800}; 
  40049. æDT MIDIRemovePort((short) refnum);
  40050. æC 
  40051.  
  40052. æKY MIDIGetSync
  40053. æFc MIDI.h
  40054. æT Function
  40055. æD pascal short MIDIGetSync(short refnum)
  40056.     = {0x203C,0x0050,midiToolNum,0xA800}; 
  40057. æDT short myVariable = MIDIGetSync((short) refnum);
  40058. æC 
  40059.  
  40060. æKY MIDISetSync
  40061. æFc MIDI.h
  40062. æT Function
  40063. æD pascal void MIDISetSync(short refnum,short sync)
  40064.     = {0x203C,0x0054,midiToolNum,0xA800}; 
  40065. æDT MIDISetSync((short) refnum,(short) sync);
  40066. æC 
  40067.  
  40068. æKY MIDIGetCurTime
  40069. æFc MIDI.h
  40070. æT Function
  40071. æD pascal long MIDIGetCurTime(short refnum)
  40072.     = {0x203C,0x0058,midiToolNum,0xA800}; 
  40073. æDT long myVariable = MIDIGetCurTime((short) refnum);
  40074. æC 
  40075.  
  40076. æKY MIDISetCurTime
  40077. æFc MIDI.h
  40078. æT Function
  40079. æD pascal void MIDISetCurTime(short refnum,long time)
  40080.     = {0x203C,0x005C,midiToolNum,0xA800}; 
  40081. æDT MIDISetCurTime((short) refnum,(long) time);
  40082. æC 
  40083.  
  40084. æKY MIDIStartTime
  40085. æFc MIDI.h
  40086. æT Function
  40087. æD pascal void MIDIStartTime(short refnum)
  40088.     = {0x203C,0x0060,midiToolNum,0xA800}; 
  40089. æDT MIDIStartTime((short) refnum);
  40090. æC 
  40091.  
  40092. æKY MIDIStopTime
  40093. æFc MIDI.h
  40094. æT Function
  40095. æD pascal void MIDIStopTime(short refnum)
  40096.     = {0x203C,0x0064,midiToolNum,0xA800}; 
  40097. æDT MIDIStopTime((short) refnum);
  40098. æC 
  40099.  
  40100. æKY MIDIPoll
  40101. æFc MIDI.h
  40102. æT Function
  40103. æD pascal void MIDIPoll(short refnum,long offsetTime)
  40104.     = {0x203C,0x0068,midiToolNum,0xA800}; 
  40105. æDT MIDIPoll((short) refnum,(long) offsetTime);
  40106. æC 
  40107.  
  40108. æKY MIDIWritePacket
  40109. æFc MIDI.h
  40110. æT Function
  40111. æD pascal OSErr MIDIWritePacket(short refnum,MIDIPacketPtr packet)
  40112.     = {0x203C,0x006C,midiToolNum,0xA800}; 
  40113. æDT OSErr myVariable = MIDIWritePacket((short) refnum,(MIDIPacketPtr) packet);
  40114. æC 
  40115.  
  40116. æKY MIDIWorldChanged
  40117. æFc MIDI.h
  40118. æT Function
  40119. æD pascal Boolean MIDIWorldChanged(OSType clientID)
  40120.     = {0x203C,0x0070,midiToolNum,0xA800}; 
  40121. æDT Boolean myVariable = MIDIWorldChanged((OSType) clientID);
  40122. æC 
  40123.  
  40124. æKY MIDIGetOffsetTime
  40125. æFc MIDI.h
  40126. æT Function
  40127. æD pascal long MIDIGetOffsetTime(short refnum)
  40128.     = {0x203C,0x0074,midiToolNum,0xA800}; 
  40129. æDT long myVariable = MIDIGetOffsetTime((short) refnum);
  40130. æC 
  40131.  
  40132. æKY MIDISetOffsetTime
  40133. æFc MIDI.h
  40134. æT Function
  40135. æD pascal void MIDISetOffsetTime(short refnum,long offsetTime)
  40136.     = {0x203C,0x0078,midiToolNum,0xA800}; 
  40137. æDT MIDISetOffsetTime((short) refnum,(long) offsetTime);
  40138. æC 
  40139.  
  40140. æKY MIDIConvertTime
  40141. æFc MIDI.h
  40142. æT Function
  40143. æD pascal long MIDIConvertTime(short srcformat,short dstformat,long time)
  40144.     = {0x203C,0x007C,midiToolNum,0xA800}; 
  40145. æDT long myVariable = MIDIConvertTime((short) srcformat,(short) dstformat,(long) time);
  40146. æC 
  40147.  
  40148. æKY MIDIGetRefCon
  40149. æFc MIDI.h
  40150. æT Function
  40151. æD pascal long MIDIGetRefCon(short refnum)
  40152.     = {0x203C,0x0080,midiToolNum,0xA800}; 
  40153. æDT long myVariable = MIDIGetRefCon((short) refnum);
  40154. æC 
  40155.  
  40156. æKY MIDISetRefCon
  40157. æFc MIDI.h
  40158. æT Function
  40159. æD pascal void MIDISetRefCon(short refnum,long refCon)
  40160.     = {0x203C,0x0084,midiToolNum,0xA800}; 
  40161. æDT MIDISetRefCon((short) refnum,(long) refCon);
  40162. æC 
  40163.  
  40164. æKY MIDIGetClRefCon
  40165. æFc MIDI.h
  40166. æT Function
  40167. æD pascal long MIDIGetClRefCon(OSType clientID)
  40168.     = {0x203C,0x0088,midiToolNum,0xA800}; 
  40169. æDT long myVariable = MIDIGetClRefCon((OSType) clientID);
  40170. æC 
  40171.  
  40172. æKY MIDISetClRefCon
  40173. æFc MIDI.h
  40174. æT Function
  40175. æD pascal void MIDISetClRefCon(OSType clientID,long refCon)
  40176.     = {0x203C,0x008C,midiToolNum,0xA800}; 
  40177. æDT MIDISetClRefCon((OSType) clientID,(long) refCon);
  40178. æC 
  40179.  
  40180. æKY MIDIGetTCFormat
  40181. æFc MIDI.h
  40182. æT Function
  40183. æD pascal short MIDIGetTCFormat(short refnum)
  40184.     = {0x203C,0x0090,midiToolNum,0xA800}; 
  40185. æDT short myVariable = MIDIGetTCFormat((short) refnum);
  40186. æC 
  40187.  
  40188. æKY MIDISetTCFormat
  40189. æFc MIDI.h
  40190. æT Function
  40191. æD pascal void MIDISetTCFormat(short refnum,short format)
  40192.     = {0x203C,0x0094,midiToolNum,0xA800}; 
  40193. æDT MIDISetTCFormat((short) refnum,(short) format);
  40194. æC 
  40195.  
  40196. æKY MIDISetRunRate
  40197. æFc MIDI.h
  40198. æT Function
  40199. æD pascal void MIDISetRunRate(short refnum,short rate,long time)
  40200.     = {0x203C,0x0098,midiToolNum,0xA800}; 
  40201. æDT MIDISetRunRate((short) refnum,(short) rate,(long) time);
  40202. æC 
  40203.  
  40204. æKY MIDIGetClientIcon
  40205. æFc MIDI.h
  40206. æT Function
  40207. æD pascal Handle MIDIGetClientIcon(OSType clientID)
  40208.     = {0x203C,0x009C,midiToolNum,0xA800}; 
  40209. æDT Handle myVariable = MIDIGetClientIcon((OSType) clientID);
  40210. æC 
  40211.  
  40212.  
  40213. æKY Notification.h
  40214. æKL NMInstall
  40215. NMRemove
  40216.  
  40217. NMProcPtr
  40218. NMRec
  40219. NMRecPtr
  40220. nmType
  40221.  
  40222. æKY nmType
  40223. æFc Notification.h
  40224. æT #define
  40225. æD #define nmType 8
  40226. æC 
  40227.  
  40228. æKY NMProcPtr
  40229. æFc Notification.h
  40230. æT typedef
  40231. æD typedef pascal void (*NMProcPtr)(struct NMRec *);
  40232. æC 
  40233.  
  40234. æKY NMRec
  40235. NMRecPtr
  40236. æFc Notification.h
  40237. æT struct
  40238. æD struct NMRec {
  40239.     QElemPtr qLink; /*next queue entry*/
  40240.     short qType; /*queue type -- ORD(nmType) = 8*/
  40241.     short nmFlags; /*reserved*/
  40242.     long nmPrivate; /*reserved*/
  40243.     short nmReserved; /*reserved*/
  40244.     short nmMark; /*item to mark in Apple menu*/
  40245.     Handle nmSIcon; /*handle to small icon*/
  40246.     Handle nmSound; /*handle to sound record*/
  40247.     StringPtr nmStr; /*string to appear in alert*/
  40248.     NMProcPtr nmResp; /*pointer to response routine*/
  40249.     long nmRefCon; /*for application use*/
  40250. };
  40251.  
  40252. typedef struct NMRec NMRec;
  40253. typedef NMRec *NMRecPtr;
  40254.  
  40255. æC 
  40256.  
  40257. æKY NMInstall
  40258. æFc Notification.h
  40259. æT Function
  40260. æTN A05E
  40261. æD pascal OSErr NMInstall(QElemPtr nmReqPtr)
  40262.     = {0x205F,0xA05E,0x3E80}; 
  40263. æDT OSErr myVariable = NMInstall((QElemPtr) nmReqPtr);
  40264. æRT 184
  40265. æC 
  40266. The Notification Manager includes two functions, one to install a notification
  40267. request and one to remove a notification request. To install a notification
  40268. request, use the function NMInstall.
  40269.  
  40270. NMInstall takes a single parameter, a pointer to a Notification Manager record.
  40271. It adds the notification request specified by that record to the notification
  40272. queue and returns a result code.
  40273.  
  40274. Result codes
  40275. noErr         0  No error
  40276. nmTypeErr  –299  Invalid qType (must be ORD(nmType))
  40277.  
  40278. æKY NMRemove
  40279. æFc Notification.h
  40280. æT Function
  40281. æTN A05F
  40282. æD pascal OSErr NMRemove(QElemPtr nmReqPtr)
  40283.     = {0x205F,0xA05F,0x3E80}; 
  40284. æDT OSErr myVariable = NMRemove((QElemPtr) nmReqPtr);
  40285. æRT 184
  40286. æC 
  40287. NMRemove removes the notification request identified by nmReqPtr from the
  40288. notification queue and returns a result code.
  40289.  
  40290. Result codes
  40291. noErr         0  No error
  40292. qErr         –1  Not in queue
  40293. nmTypeErr  –299  Invalid qType (must be ORD(nmType))
  40294.  
  40295.  
  40296. æKY OSEvents.h
  40297. æKL FlushEvents
  40298. GetEvQHdr
  40299. GetOSEvent
  40300. OSEventAvail
  40301. PostEvent
  40302. PPostEvent
  40303. SetEventMask
  40304.  
  40305. EvQEl
  40306. EvQElPtr
  40307.  
  40308. æKY EvQEl
  40309. EvQElPtr
  40310. æFc OSEvents.h
  40311. æT struct
  40312. æD struct EvQEl {
  40313.     QElemPtr qLink;
  40314.     short qType;
  40315.     short evtQWhat; /*this part is identical to the EventRecord as...*/
  40316.     long evtQMessage; /*defined in ToolIntf*/
  40317.     long evtQWhen;
  40318.     Point evtQWhere;
  40319.     short evtQModifiers;
  40320. };
  40321.  
  40322. typedef struct EvQEl EvQEl;
  40323. typedef EvQEl *EvQElPtr;
  40324.  
  40325. æC 
  40326. »STRUCTURE OF THE EVENT QUEUE
  40327. _______________________________________________________________________________
  40328.  
  40329. The event queue is a standard Macintosh Operating System queue, as described in the
  40330. Operating System Utilities chapter. Most programmers will never need to access the
  40331. event queue directly; some advanced programmers, though, may need to do so for special
  40332. purposes.
  40333.  
  40334. Each entry in the event queue contains information about an event:
  40335.  
  40336. TYPE  EvQEl = RECORD
  40337.                 qLink:          QElemPtr;  {next queue entry}
  40338.                 qType:          INTEGER;   {queue type}
  40339.                 evtQWhat:       INTEGER;   {event code}
  40340.                 evtQMessage:    LONGINT;   {event message}
  40341.                 evtQWhen:       LONGINT;   {ticks since startup}
  40342.                 evtQWhere:      Point;     {mouse location}
  40343.                 evtQModifiers:  INTEGER    {modifier flags}
  40344.               END;
  40345.  
  40346. QLink points to the next entry in the queue, and qType indicates the queue type,
  40347. which must be ORD(evType). The remaining five fields of the event queue entry contain
  40348. exactly the same information about the event as do the fields of the event record for
  40349. that event; see the Toolbox Event Manager chapter for a detailed description of the
  40350. contents of these fields.
  40351.  
  40352. You can get a pointer to the header of the event queue by calling the Operating
  40353. System Event Manager function GetEvQHdr.
  40354.  
  40355. æKY PostEvent
  40356. æFc OSEvents.h
  40357. æT Function
  40358. æD pascal OSErr PostEvent(short eventNum,long eventMsg); 
  40359. æDT OSErr myVariable = PostEvent((short) eventNum,(long) eventMsg);
  40360. æRI II-68
  40361. æC 
  40362. Trap macro  _PostEvent
  40363. On entry    A0:  eventCode (word)
  40364.             D0:  eventMsg (long word)
  40365. On exit     D0:  result code (word)
  40366.  
  40367. PostEvent places in the event queue an event of the type designated by eventCode,
  40368. with the event message specified by eventMsg and with the current time, mouse location,
  40369. and state of the modifier keys and mouse button. It returns a result code (of type
  40370. OSErr, defined as INTEGER in the Operating System Utilities) equal to one of the
  40371. following predefined constants:
  40372.  
  40373. CONST  noErr        = 0;    {no error (event posted)}
  40374.        evtNotEnb    = 1;    {event type not designated in system event mask}
  40375.  
  40376. Warning:  Be very careful when posting any events other than your own
  40377.           application-defined events into the queue; attempting to post an
  40378.           activate or update event, for example, will interfere with the
  40379.           internal operation of the Toolbox Event Manager, since such events
  40380.           aren’t normally placed in the queue at all.
  40381.  
  40382. Warning:  If you use PostEvent to repost an event, remember that the event
  40383.           time, location, and state of the modifier keys and mouse button
  40384.           will all be changed from their values when the event was originally
  40385.           posted, possibly altering the meaning of the event.
  40386.  
  40387. æKY PPostEvent
  40388. æFc OSEvents.h
  40389. æT Function
  40390. æD pascal OSErr PPostEvent(short eventCode,long eventMsg,EvQElPtr *qEl); 
  40391. æDT OSErr myVariable = PPostEvent((short) eventCode,(long) eventMsg,(EvQElPtr *) qEl);
  40392. æC 
  40393. Trap macro  _PPostEvent
  40394. On entry    A0:  eventCode (word)
  40395.             D0:  eventMsg (long word)
  40396. On exit     A0:  pointer to event queue entry
  40397.  
  40398. PPostEvent is identical to PostEvent except that it returns a pointer to the created
  40399. queue entry.
  40400.  
  40401. æKY OSEventAvail
  40402. æFc OSEvents.h
  40403. æT Function
  40404. æD pascal Boolean OSEventAvail(short mask,EventRecord *theEvent); 
  40405. æDT Boolean myVariable = OSEventAvail((short) mask,(EventRecord *) theEvent);
  40406. æRI II-70
  40407. æC 
  40408. Trap macro  _OSEventAvail
  40409. On entry    A0:  pointer to event record theEvent
  40410.             D0:  eventMask (word)
  40411. On exit     D0:  0 if non-null event returned, or –1 if null event
  40412.                  returned (byte)
  40413.  
  40414. OSEventAvail works exactly the same as GetOSEvent (above) except that it
  40415. doesn’t remove the event from the event queue.
  40416.  
  40417. Note:  An event returned by OSEventAvail will not be accessible later if
  40418.        in the meantime the queue becomes full and the event is discarded
  40419.        from it; since the events discarded are always the oldest ones in
  40420.        the queue, however, this will happen only in an unusually busy
  40421.        environment.
  40422.  
  40423. æKY GetOSEvent
  40424. æFc OSEvents.h
  40425. æT Function
  40426. æD pascal Boolean GetOSEvent(short mask,EventRecord *theEvent); 
  40427. æDT Boolean myVariable = GetOSEvent((short) mask,(EventRecord *) theEvent);
  40428. æRT 85
  40429. æRI II-69, N85-1
  40430. æC 
  40431. Trap macro  _GetOSEvent
  40432. On entry    A0:  pointer to event record theEvent
  40433.             D0:  eventMask (word)
  40434. On exit     D0:  0 if non-null event returned, or –1 if null event
  40435.                  returned (byte)
  40436.  
  40437. GetOSEvent returns the next available event of a specified type or types and removes
  40438. it from the event queue. The event is returned as the value of the parameter theEvent.
  40439. The eventMask parameter specifies which event types are of interest. GetOSEvent will
  40440. return the next available event of any type designated by the mask. If no event of
  40441. any of the designated types is available, GetOSEvent returns a null event and a
  40442. function result of FALSE; otherwise it returns TRUE.
  40443.  
  40444. Note:  Unlike the Toolbox Event Manager function GetNextEvent, GetOSEvent
  40445.        doesn’t call the Desk Manager to see whether the system wants to
  40446.        intercept and respond to the event; nor does it perform GetNextEvent’s
  40447.        processing of the alarm and Command-Shift-number combinations.
  40448.  
  40449. æKY FlushEvents
  40450. æFc OSEvents.h
  40451. æT Function
  40452. æD pascal void FlushEvents(short whichMask,short stopMask)
  40453.     = {0x201F,0xA032}; 
  40454. æDT FlushEvents((short) whichMask,(short) stopMask);
  40455. æRI II-69, P-31, 170
  40456. æC 
  40457. Trap macro  _FlushEvents
  40458. On entry    D0:    low-order word:    eventMask
  40459.                    high-order word:   stopMask
  40460. On exit     D0:    0 or event code (word)
  40461.  
  40462. FlushEvents removes events from the event queue as specified by the given event
  40463. masks. It removes all events of the type or types specified by eventMask, up to but
  40464. not including the first event of any type specified by stopMask; if the event queue
  40465. doesn’t contain any events of the types specified by eventMask, it does nothing. To
  40466. remove all events specified by eventMask, use a stopMask value of 0.
  40467.  
  40468. At the beginning of your application, it’s usually a good idea to call FlushEvents(everyEvent,0)
  40469. to empty the event queue of any stray events that may have been left lying around,
  40470. such as unprocessed keystrokes typed to the Finder.
  40471.  
  40472. Assembly-language note:  On exit from this routine, D0 contains 0 if all
  40473.                          events were removed from the queue or, if not, an
  40474.                          event code specifying the type of event that caused
  40475.                          the removal process to stop.
  40476.  
  40477. æKY SetEventMask
  40478. æFc OSEvents.h
  40479. æT Function
  40480. æD pascal void SetEventMask(short theMask)
  40481.     = {0x31DF,0x0144}; 
  40482. æDT SetEventMask((short) theMask);
  40483. æRT 202
  40484. æRI II-70
  40485. æC 
  40486. [Not in ROM]
  40487.  
  40488. SetEventMask sets the system event mask to the specified event mask. The Operating
  40489. System Event Manager will post only those event types that correspond to bits set in
  40490. the mask. (As usual, it will not post activate and update events, which are generated
  40491. by the Window Manager and not stored in the event queue.) The system event mask is
  40492. initially set to post all except key-up events.
  40493.  
  40494. Warning:  Because desk accessories may rely on receiving certain types of
  40495.           events, your application shouldn’t set the system event mask to
  40496.           prevent any additional types (besides key-up) from being posted.
  40497.           You should use SetEventMask only to enable key-up events in the
  40498.           unusual case that your application needs to respond to them.
  40499.  
  40500. Assembly-language note:  The system event mask is available to assembly-
  40501.                          language programmers in the global variable SysEvtMask.
  40502.  
  40503. æKY GetEvQHdr
  40504. æFc OSEvents.h
  40505. æT Function
  40506. æD pascal QHdrPtr GetEvQHdr(void); 
  40507. æDT QHdrPtr myVariable = GetEvQHdr()(void);
  40508. æRI II-71
  40509. æC  
  40510. [Not in ROM]
  40511.  
  40512. GetEvQHdr returns a pointer to the header of the event queue.
  40513.  
  40514. Assembly-language note:  The global variable EventQueue contains the
  40515.                          header of the event queue.
  40516.  
  40517.  
  40518. æKY OSUtils.h
  40519. æKL Date2Secs
  40520. Delay
  40521. Dequeue
  40522. DTInstall
  40523. Enqueue
  40524. Environs
  40525. EqualString
  40526. equalstring
  40527. FlushDataCache
  40528. FlushInstructionCache
  40529. GetDateTime
  40530. GetMMUMode
  40531. GetSysPPtr
  40532. GetTime
  40533. GetTrapAddress
  40534. HandAndHand
  40535. HandToHand
  40536. InitUtil
  40537. KeyTrans
  40538. NGetTrapAddress
  40539. NSetTrapAddress
  40540. PtrAndHand
  40541. PtrToHand
  40542. PtrToXHand
  40543. ReadDateTime
  40544. relstring
  40545. RelString
  40546. Restart
  40547. Secs2Date
  40548. SetA5
  40549. SetCurrentA5
  40550. SetDateTime
  40551. SetTime
  40552. SetTrapAddress
  40553. SwapDataCache
  40554. SwapInstructionCache
  40555. SwapMMUMode
  40556. SysBeep
  40557. SysEnvirons
  40558. uprstring
  40559. UprString
  40560. WriteParam
  40561.  
  40562. curSysEnvVers
  40563. DateTimeRec
  40564. drvQType
  40565. dtQType
  40566. dummyType
  40567. env512KE
  40568. env68000
  40569. env68010
  40570. env68020
  40571. env68030
  40572. env68040
  40573. envAExtendKbd
  40574. envCPUUnknown
  40575. envExtISOADBKbd
  40576. envMac
  40577. envMacAndPad
  40578. envMachUnknown
  40579. envMacII
  40580. envMacIIci
  40581. envMacIIcx
  40582. envMacIIx
  40583. envMacKbd
  40584. envMacPlus
  40585. envMacPlusKbd
  40586. envPortable
  40587. envPrtblADBKbd
  40588. envPrtblISOKbd
  40589. envSE
  40590. envSE30
  40591. envStandADBKbd
  40592. envStdISOADBKbd
  40593. envUnknownKbd
  40594. envXL
  40595. evType
  40596. false32b
  40597. fsQType
  40598. ioQType
  40599. OSTrap
  40600. QElem
  40601. QElemPtr
  40602. QHdr
  40603. QHdrPtr
  40604. QTypes
  40605. sIQType
  40606. sortsAfter
  40607. sortsBefore
  40608. sortsEqual
  40609. SysEnvRec
  40610. SysParmType
  40611. SysPPtr
  40612. ToolTrap
  40613. TrapType
  40614. true32b
  40615. useAsync
  40616. useATalk
  40617. useExtClk
  40618. useFree
  40619. useMIDI
  40620. VBLProcPtr
  40621. VBLTask
  40622. vType
  40623.  
  40624. æKY useFree
  40625. æFc OSUtils.h
  40626. æT #define
  40627. æD #define useFree 0
  40628. æC 
  40629.  
  40630. æKY useATalk
  40631. æFc OSUtils.h
  40632. æT #define
  40633. æD #define useATalk 1
  40634. æC 
  40635.  
  40636. æKY useAsync
  40637. æFc OSUtils.h
  40638. æT #define
  40639. æD #define useAsync 2
  40640. æC 
  40641.  
  40642. æKY useExtClk
  40643. æFc OSUtils.h
  40644. æT #define
  40645. æD #define useExtClk 3 /*Externally clocked*/
  40646. æC 
  40647.  
  40648. æKY useMIDI
  40649. æFc OSUtils.h
  40650. æT #define
  40651. æD #define useMIDI 4
  40652. æC 
  40653.  
  40654. æKY curSysEnvVers
  40655. æFc OSUtils.h
  40656. æT #define
  40657. æD 
  40658. /* *** Environs Equates *** */
  40659.  
  40660. #define curSysEnvVers 2 /*Updated to equal latest SysEnvirons version*/
  40661. æC 
  40662.  
  40663. æKY envMac
  40664. æFc OSUtils.h
  40665. æT #define
  40666. æD 
  40667. /*  Machine Types  */
  40668.  
  40669. #define envMac -1
  40670. æC 
  40671.  
  40672. æKY envXL
  40673. æFc OSUtils.h
  40674. æT #define
  40675. æD #define envXL -2
  40676. æC 
  40677.  
  40678. æKY envMachUnknown
  40679. æFc OSUtils.h
  40680. æT #define
  40681. æD #define envMachUnknown 0
  40682. æC 
  40683.  
  40684. æKY env512KE
  40685. æFc OSUtils.h
  40686. æT #define
  40687. æD #define env512KE 1
  40688. æC 
  40689.  
  40690. æKY envMacPlus
  40691. æFc OSUtils.h
  40692. æT #define
  40693. æD #define envMacPlus 2
  40694. æC 
  40695.  
  40696. æKY envSE
  40697. æFc OSUtils.h
  40698. æT #define
  40699. æD #define envSE 3
  40700. æC 
  40701.  
  40702. æKY envMacII
  40703. æFc OSUtils.h
  40704. æT #define
  40705. æD #define envMacII 4
  40706. æC 
  40707.  
  40708. æKY envMacIIx
  40709. æFc OSUtils.h
  40710. æT #define
  40711. æD #define envMacIIx 5
  40712. æC 
  40713.  
  40714. æKY envMacIIcx
  40715. æFc OSUtils.h
  40716. æT #define
  40717. æD #define envMacIIcx 6
  40718. æC 
  40719.  
  40720. æKY envSE30
  40721. æFc OSUtils.h
  40722. æT #define
  40723. æD #define envSE30 7
  40724. æC 
  40725.  
  40726. æKY envPortable
  40727. æFc OSUtils.h
  40728. æT #define
  40729. æD #define envPortable 8
  40730. æC 
  40731.  
  40732. æKY envMacIIci
  40733. æFc OSUtils.h
  40734. æT #define
  40735. æD #define envMacIIci 9
  40736. æC 
  40737.  
  40738. æKY envCPUUnknown
  40739. æFc OSUtils.h
  40740. æT #define
  40741. æD 
  40742. /* CPU types */
  40743.  
  40744. #define envCPUUnknown 0
  40745. æC 
  40746.  
  40747. æKY env68000
  40748. æFc OSUtils.h
  40749. æT #define
  40750. æD #define env68000 1
  40751. æC 
  40752.  
  40753. æKY env68010
  40754. æFc OSUtils.h
  40755. æT #define
  40756. æD #define env68010 2
  40757. æC 
  40758.  
  40759. æKY env68020
  40760. æFc OSUtils.h
  40761. æT #define
  40762. æD #define env68020 3
  40763. æC 
  40764.  
  40765. æKY env68030
  40766. æFc OSUtils.h
  40767. æT #define
  40768. æD #define env68030 4
  40769. æC 
  40770.  
  40771. æKY env68040
  40772. æFc OSUtils.h
  40773. æT #define
  40774. æD #define env68040 5
  40775. æC 
  40776.  
  40777. æKY envUnknownKbd
  40778. æFc OSUtils.h
  40779. æT #define
  40780. æD 
  40781. /* Keyboard types */
  40782.  
  40783. #define envUnknownKbd 0
  40784. æC 
  40785.  
  40786. æKY envMacKbd
  40787. æFc OSUtils.h
  40788. æT #define
  40789. æD #define envMacKbd 1
  40790. æC 
  40791.  
  40792. æKY envMacAndPad
  40793. æFc OSUtils.h
  40794. æT #define
  40795. æD #define envMacAndPad 2
  40796. æC 
  40797.  
  40798. æKY envMacPlusKbd
  40799. æFc OSUtils.h
  40800. æT #define
  40801. æD #define envMacPlusKbd 3
  40802. æC 
  40803.  
  40804. æKY envAExtendKbd
  40805. æFc OSUtils.h
  40806. æT #define
  40807. æD #define envAExtendKbd 4
  40808. æC 
  40809.  
  40810. æKY envStandADBKbd
  40811. æFc OSUtils.h
  40812. æT #define
  40813. æD #define envStandADBKbd 5
  40814. æC 
  40815.  
  40816. æKY envPrtblADBKbd
  40817. æFc OSUtils.h
  40818. æT #define
  40819. æD #define envPrtblADBKbd 6
  40820. æC 
  40821.  
  40822. æKY envPrtblISOKbd
  40823. æFc OSUtils.h
  40824. æT #define
  40825. æD #define envPrtblISOKbd 7
  40826. æC 
  40827.  
  40828. æKY envStdISOADBKbd
  40829. æFc OSUtils.h
  40830. æT #define
  40831. æD #define envStdISOADBKbd 8
  40832. æC 
  40833.  
  40834. æKY envExtISOADBKbd
  40835. æFc OSUtils.h
  40836. æT #define
  40837. æD #define envExtISOADBKbd 9
  40838. æC 
  40839.  
  40840. æKY false32b
  40841. æFc OSUtils.h
  40842. æT #define
  40843. æD #define false32b 0 /*24 bit addressing error*/
  40844. æC 
  40845.  
  40846. æKY true32b
  40847. æFc OSUtils.h
  40848. æT #define
  40849. æD #define true32b 1 /*32 bit addressing error*/
  40850. æC 
  40851.  
  40852. æKY sortsBefore
  40853. æFc OSUtils.h
  40854. æT #define
  40855. æD 
  40856. /* result types for RelString Call */
  40857.  
  40858. #define sortsBefore -1 /*first string < second string*/
  40859. æC 
  40860.  
  40861. æKY sortsEqual
  40862. æFc OSUtils.h
  40863. æT #define
  40864. æD #define sortsEqual 0 /*first string = second string*/
  40865. æC 
  40866.  
  40867. æKY sortsAfter
  40868. æFc OSUtils.h
  40869. æT #define
  40870. æD #define sortsAfter 1 /*first string > second string*/
  40871. æC 
  40872.  
  40873. æKY QTypes
  40874. dummyType
  40875. vType
  40876. ioQType
  40877. drvQType
  40878. evType
  40879. fsQType
  40880. sIQType
  40881. dtQType
  40882. æFc OSUtils.h
  40883. æT enum
  40884. æD enum {dummyType,vType,ioQType,drvQType,evType,fsQType,sIQType,dtQType};
  40885. typedef unsigned short QTypes;
  40886. æC 
  40887.  
  40888. æKY TrapType
  40889. OSTrap
  40890. ToolTrap
  40891. æFc OSUtils.h
  40892. æT enum
  40893. æD enum {OSTrap,ToolTrap};
  40894. typedef unsigned char TrapType;
  40895. æC 
  40896.  
  40897. æKY SysParmType
  40898. SysPPtr
  40899. æFc OSUtils.h
  40900. æT struct
  40901. æD struct SysParmType {
  40902.     char valid;
  40903.     char aTalkA;
  40904.     char aTalkB;
  40905.     char config;
  40906.     short portA;
  40907.     short portB;
  40908.     long alarm;
  40909.     short font;
  40910.     short kbdPrint;
  40911.     short volClik;
  40912.     short misc;
  40913. };
  40914.  
  40915. typedef struct SysParmType SysParmType;
  40916. typedef SysParmType *SysPPtr;
  40917.  
  40918. æC 
  40919. _______________________________________________________________________________
  40920.  
  40921. »PARAMETER RAM
  40922. _______________________________________________________________________________
  40923.  
  40924. Various settings, such as those specified by the user by means of the Control Panel
  40925. desk accessory, need to be preserved when the Macintosh is off so they will still be
  40926. present at the next system startup. This information is kept in parameter RAM, 20
  40927. bytes that are stored in the clock chip together with the current date and time
  40928. setting. The clock chip is powered by a battery when the system is off, thereby
  40929. preserving all the settings stored in it.
  40930.  
  40931. You may find it necessary to read the values in parameter RAM or even change them
  40932. (for example, if you create a desk accessory like the Control Panel). Since the clock
  40933. chip itself is difficult to access, its contents are copied into low memory at system
  40934. startup. You read and change parameter RAM through this low-memory copy.
  40935.  
  40936. Note:  Certain values from parameter RAM are used so frequently that special
  40937.        routines have been designed to return them (for example, the Toolbox
  40938.        Event Manager function GetDblTime). These routines are discussed in
  40939.        other chapters where appropriate.
  40940.  
  40941. Assembly-language note:  The low-memory copy of parameter RAM begins at the
  40942.                          address SysParam; the various portions of the copy
  40943.                          can be accessed through individual global variables,
  40944.                          listed in the summary at the end of this chapter.
  40945.                          Some of these are copied into other global variables
  40946.                          at system startup for even easier access; for example,
  40947.                          the auto-key threshold and rate, which are contained
  40948.                          in the variable SPKbd in the copy of parameter RAM,
  40949.                          are copied into the variables KeyThresh and
  40950.                          KeyRepThresh. Each such variable is discussed in the
  40951.                          appropriate chapter.
  40952.  
  40953. The date and time setting is also copied at system startup from the clock chip into
  40954. its own low-memory location. It’s stored as a number of seconds since midnight,
  40955. January 1, 1904, and is updated every second. The maximum value, $FFFFFFFF, corresponds
  40956. to 6:28:15 AM, February 6, 2040; after that, it wraps around to midnight, January 1,
  40957. 1904.
  40958.  
  40959. Assembly-language note:  The low-memory location containing the date and
  40960.                          time is the global variable Time.
  40961.  
  40962. The structure of parameter RAM is represented by the following data type:
  40963.  
  40964. TYPE  SysParmType = RECORD
  40965.                       valid:     Byte;     {validity status}
  40966.                       aTalkA:    Byte;     {AppleTalk node ID hint for modem }
  40967.                                            { port}
  40968.                       aTalkB:    Byte;     {AppleTalk node ID hint for printer }
  40969.                                            { port}
  40970.                       config:    Byte;     {use types for serial ports}
  40971.                       portA:     INTEGER;  {modem port configuration}
  40972.                       portB:     INTEGER;  {printer port configuration}
  40973.                       alarm:     LONGINT;  {alarm setting}
  40974.                       font:      INTEGER;  {application font number minus 1}
  40975.                       kbdPrint:  INTEGER;  {auto-key settings, printer }
  40976.                                            { connection}
  40977.                       volClik:   INTEGER;  {speaker volume, double-click, }
  40978.                                            { caret blink}
  40979.                       misc:      INTEGER   {mouse scaling, startup disk, }
  40980.                                            { menu blink}
  40981.                     END;
  40982.  
  40983.       SysPPtr = ^SysParmType;
  40984.  
  40985. The valid field contains the validity status of the clock chip:  Whenever you successfully
  40986. write to the clock chip, $A8 is stored in this byte. The validity status is examined
  40987. when the clock chip is read at system startup. It won’t be $A8 if a hardware problem
  40988. prevented the values from being written; in this case, the low-memory copy of parameter
  40989. RAM is set to the default values shown in the table below, and these values are then
  40990. written to the clock chip itself. (The meanings of the parameters are explained below
  40991. in the descriptions of the various fields.)
  40992.  
  40993.   Parameter                          Default value
  40994.  
  40995.   Validity status                    $A8
  40996.   Node ID hint for modem port        0
  40997.   Node ID hint for printer port      0
  40998.   Use types for serial ports         0 (both ports)
  40999.   Modem port configuration           9600 baud, 8 data bits, 2 stop bits,
  41000.                                      no parity
  41001.   Printer port configuration         Same as for modem port
  41002.   Alarm setting                      0 (midnight, January 1, 1904)
  41003.   Application font number minus 1    2 (Geneva)
  41004.   Auto-key threshold                 6 (24 ticks)
  41005.   Auto-key rate                      3 (6 ticks)
  41006.   Printer connection                 0 (printer port)
  41007.   Speaker volume                     3 (medium)
  41008.   Double-click time                  8 (32 ticks)
  41009.   Caret-blink time                   8 (32 ticks)
  41010.   Mouse scaling                      1 (on)
  41011.   Preferred system startup disk      0 (internal drive)
  41012.   Menu blink                         3
  41013.  
  41014. Warning:  Your program must not use bits indicated below as “reserved for
  41015.           future use” in parameter RAM, since future Macintosh software
  41016.           features will use them.
  41017.  
  41018. The aTalkA and aTalkB fields are used by the AppleTalk Manager; they’re described in
  41019. the manual Inside AppleTalk.
  41020.  
  41021. The config field indicates which device or devices may use each of the serial ports;
  41022. for details, see the section “Calling the AppleTalk Manager from Assembly Language”
  41023. in the AppleTalk Manager chapter.
  41024.  
  41025. The portA and portB fields contain the baud rates, data bits, stop bits, and parity
  41026. for the device drivers using the modem port (“port A”) and printer port
  41027. (“port B”). An explanation of these terms and the exact format of the information are
  41028. given in the Serial Drivers chapter.
  41029.  
  41030. The alarm field contains the alarm setting in seconds since midnight, January 1,
  41031. 1904.
  41032.  
  41033. The font field contains 1 less than the number of the application font. See the Font
  41034. Manager chapter for a list of font numbers.
  41035.  
  41036. Bit 0 of the kbdPrint field (Figure 1) designates whether the printer (if any) is
  41037. connected to the printer port (0) or the modem port (1). Bits 8-11 of this field
  41038. contain the auto-key rate, the rate of the repeat when a character key is held down;
  41039. this value is stored in two-tick units. Bits 12-15 contain the auto-key threshold,
  41040. the length of time the key must be held down before it begins to repeat; it’s stored
  41041. in four-tick units.
  41042.  
  41043. •••Refer to Figure 1.•••
  41044.  
  41045. Figure 1–The KbdPrint Field
  41046.  
  41047. Bits 0-3 of the volClik field (Figure 2) contain the caret-blink time, and bits 4-7
  41048. contain the double-click time; both values are stored in four-tick units. The caret-blink
  41049. time is the interval between blinks of the caret that marks the insertion point in
  41050. text. The double-click time is the greatest interval between a mouse-up and mouse-down
  41051. event that would qualify two mouse clicks as a double-click. Bits 8-10 of the volClik
  41052. field contain the speaker volume setting, which ranges from silent (0) to loud (7).
  41053.  
  41054. Note:  The Sound Driver procedure SetSoundVol changes the speaker volume
  41055.        without changing the setting in parameter RAM, so it’s possible for
  41056.        the actual volume to be different from this setting.
  41057.  
  41058. Bits 2 and 3 of the misc field (Figure 3) contain a value from 0 to 3 designating how
  41059. many times a menu item will blink when it’s chosen. Bit 4 of this field indicates
  41060. whether the preferred disk to use to start up the system is in the internal (0) or
  41061. the external (1) drive; if there’s any problem using the disk in the specified drive,
  41062. the other drive will be used.
  41063.  
  41064. •••Refer to Figure 2.•••
  41065.  
  41066. Figure 2–The VolClik Field
  41067.  
  41068. •••Refer to Figure 3.•••
  41069.  
  41070. Figure 3–The Misc Field
  41071.  
  41072. Finally, bit 6 of the misc field designates whether mouse scaling is on (1) or off
  41073. (0). If mouse scaling is on, the system looks every sixtieth of a second at whether
  41074. the mouse has moved; if in that time the sum of the mouse’s horizontal and vertical
  41075. changes in position is greater than the mouse-scaling threshold
  41076. (normally six pixels), then the cursor will move twice as far horizontally and vertically
  41077. as it would if mouse scaling were off.
  41078.  
  41079. Assembly-language note:  The mouse-scaling threshold is contained in the
  41080.                          global variable CrsrThresh.
  41081.  
  41082. æKY QElem
  41083. QElemPtr
  41084. æFc OSUtils.h
  41085. æT struct
  41086. æD struct QElem {
  41087.     struct QElem *qLink;
  41088.     short qType;
  41089.     short qData[1];
  41090. };
  41091.  
  41092. typedef struct QElem QElem;
  41093. typedef QElem *QElemPtr;
  41094.  
  41095. æC 
  41096. _______________________________________________________________________________
  41097.  
  41098. »OPERATING SYSTEM QUEUES
  41099. _______________________________________________________________________________
  41100.  
  41101. Some of the information used by the Operating System is stored in data structures
  41102. called queues. A queue is a list of identically structured entries linked together by
  41103. pointers. Queues are used to keep track of VBL tasks, I/O requests, events, mounted
  41104. volumes, and disk drives (or other block-formatted devices).
  41105.  
  41106. A standard Operating System queue has a header with the following structure:
  41107.  
  41108. TYPE  QHdr = RECORD
  41109.                qFlags:    INTEGER;    {queue flags}
  41110.                qHead:    QElemPtr;    {first queue entry}
  41111.                qTail:    QElemPtr    {last queue entry}
  41112.              END;
  41113.  
  41114.       QHdrPtr = ^QHdr;
  41115.  
  41116. QFlags contains information (usually flags) that’s different for each queue type.
  41117. QHead points to the first entry in the queue, and qTail points to the last entry in
  41118. the queue. The entries within each type of queue are different; the Operating System
  41119. uses the following variant record to access them:
  41120.  
  41121. TYPE  QTypes = (dummyType,
  41122.                 vType,       {vertical retrace queue type}
  41123.                 ioQType,     {file I/O or driver I/O queue type}
  41124.                 drvQType,    {drive queue type}
  41125.                 evType,      {event queue type}
  41126.                 fsQType);    {volume-control-block queue type}
  41127.       QElem  = RECORD
  41128.                 CASE QTypes OF
  41129.                   vType:     (vblQElem:  VBLTask);
  41130.                   ioQType:   (ioQElem:  ParamBlockRec);
  41131.                   drvQType:  (drvQElem:  DrvQEl);
  41132.                   evType:    (evQElem:  EvQEl);
  41133.                   fsQType:   (vcbQElem:  VCB)
  41134.                END;
  41135.  
  41136.       QElemPtr = ^QElem;
  41137.  
  41138. All entries in queues, regardless of the queue type, begin with four bytes of flags
  41139. followed by a pointer to the next queue entry. The entries are linked through these
  41140. pointers; each one points to the pointer field in the next entry. In Pascal, the data
  41141. type of the pointer is QElemPtr, and the data type of the entry begins with the
  41142. pointer field. Consequently, the flag bytes are inaccessible from Pascal.
  41143.  
  41144. Following the pointer to the next entry, each entry contains an integer designating
  41145. the queue type (for example, ORD(evType) for the event queue). The exact structure of
  41146. the rest of the entry depends on the type of queue; for more information, see the
  41147. chapter that discusses that queue in detail.
  41148.  
  41149. æKY QHdr
  41150. QHdrPtr
  41151. æFc OSUtils.h
  41152. æT struct
  41153. æD struct QHdr {
  41154.     short qFlags;
  41155.     QElemPtr qHead;
  41156.     QElemPtr qTail;
  41157. };
  41158.  
  41159. typedef struct QHdr QHdr;
  41160. typedef QHdr *QHdrPtr;
  41161.  
  41162. æC 
  41163. _______________________________________________________________________________
  41164.  
  41165. »OPERATING SYSTEM QUEUES
  41166. _______________________________________________________________________________
  41167.  
  41168. Some of the information used by the Operating System is stored in data structures
  41169. called queues. A queue is a list of identically structured entries linked together by
  41170. pointers. Queues are used to keep track of VBL tasks, I/O requests, events, mounted
  41171. volumes, and disk drives (or other block-formatted devices).
  41172.  
  41173. A standard Operating System queue has a header with the following structure:
  41174.  
  41175. TYPE  QHdr = RECORD
  41176.                qFlags:    INTEGER;    {queue flags}
  41177.                qHead:    QElemPtr;    {first queue entry}
  41178.                qTail:    QElemPtr    {last queue entry}
  41179.              END;
  41180.  
  41181.       QHdrPtr = ^QHdr;
  41182.  
  41183. QFlags contains information (usually flags) that’s different for each queue type.
  41184. QHead points to the first entry in the queue, and qTail points to the last entry in
  41185. the queue. The entries within each type of queue are different; the Operating System
  41186. uses the following variant record to access them:
  41187.  
  41188. TYPE  QTypes = (dummyType,
  41189.                 vType,       {vertical retrace queue type}
  41190.                 ioQType,     {file I/O or driver I/O queue type}
  41191.                 drvQType,    {drive queue type}
  41192.                 evType,      {event queue type}
  41193.                 fsQType);    {volume-control-block queue type}
  41194.       QElem  = RECORD
  41195.                 CASE QTypes OF
  41196.                   vType:     (vblQElem:  VBLTask);
  41197.                   ioQType:   (ioQElem:  ParamBlockRec);
  41198.                   drvQType:  (drvQElem:  DrvQEl);
  41199.                   evType:    (evQElem:  EvQEl);
  41200.                   fsQType:   (vcbQElem:  VCB)
  41201.                END;
  41202.  
  41203.       QElemPtr = ^QElem;
  41204.  
  41205. All entries in queues, regardless of the queue type, begin with four bytes of flags
  41206. followed by a pointer to the next queue entry. The entries are linked through these
  41207. pointers; each one points to the pointer field in the next entry. In Pascal, the data
  41208. type of the pointer is QElemPtr, and the data type of the entry begins with the
  41209. pointer field. Consequently, the flag bytes are inaccessible from Pascal.
  41210.  
  41211. Following the pointer to the next entry, each entry contains an integer designating
  41212. the queue type (for example, ORD(evType) for the event queue). The exact structure of
  41213. the rest of the entry depends on the type of queue; for more information, see the
  41214. chapter that discusses that queue in detail.
  41215.  
  41216. æKY DateTimeRec
  41217. æFc OSUtils.h
  41218. æT struct
  41219. æD struct DateTimeRec {
  41220.     short year;
  41221.     short month;
  41222.     short day;
  41223.     short hour;
  41224.     short minute;
  41225.     short second;
  41226.     short dayOfWeek;
  41227. };
  41228.  
  41229. typedef struct DateTimeRec DateTimeRec;
  41230. æC 
  41231. The following utilities are for reading and setting the date and time stored in the
  41232. clock chip. Reading the date and time is a fairly common operation; setting it is
  41233. somewhat rarer, but could be necessary for implementing a desk accessory like the
  41234. Control Panel.
  41235.  
  41236. The date and time setting is stored as an unsigned number of seconds since midnight,
  41237. January 1, 1904; you can use a utility routine to convert this to a date/time record.
  41238. Date/time records are defined as follows:
  41239.  
  41240. TYPE  DateTimeRec = RECORD
  41241.                       year:       INTEGER;  {1904 to 2040}
  41242.                       month:      INTEGER;  {1 to 12 for January to December}
  41243.                       day:        INTEGER;  {1 to 31}
  41244.                       hour:       INTEGER;  {0 to 23}
  41245.                       minute:     INTEGER;  {0 to 59}
  41246.                       second:     INTEGER;  {0 to 59}
  41247.                       dayOfWeek:  INTEGER   {1 to 7 for Sunday to Saturday}
  41248.                     END;
  41249.  
  41250. æKY SysEnvRec
  41251. æFc OSUtils.h
  41252. æT struct
  41253. æD struct SysEnvRec {
  41254.     short environsVersion;
  41255.     short machineType;
  41256.     short systemVersion;
  41257.     short processor;
  41258.     Boolean hasFPU;
  41259.     Boolean hasColorQD;
  41260.     short keyBoardType;
  41261.     short atDrvrVersNum;
  41262.     short sysVRefNum;
  41263. };
  41264.  
  41265. typedef struct SysEnvRec SysEnvRec;
  41266. æC 
  41267. The system environment record for version 1 of SysEnvirons contains the following
  41268. fields:
  41269.  
  41270. TYPE  SysEnvRec = RECORD
  41271.                     environsVersion:  INTEGER;
  41272.                     machineType:      INTEGER;
  41273.                     systemVersion:    INTEGER;
  41274.                     processor:        INTEGER;
  41275.                     hasFPU:           BOOLEAN;
  41276.                     hasColorQD:       BOOLEAN;
  41277.                     keyBoardType:     INTEGER;
  41278.                     atDrvrVersNum:    INTEGER;
  41279.                     sysVRefNum:       INTEGER
  41280.                   END;
  41281.  
  41282. New versions of the call will add fields to this record.  To distinguish between
  41283. different versions of the call, and thereby between the different sizes of records
  41284. they return, SysEnvirons returns its version number in the environsVersion field.  If
  41285. you request version 2, for instance, but only version 1 is available, the environsVersion
  41286. field will contain the value 1, and the result code envVersTooBig will be returned. 
  41287. This tells you that only the information for version 1 has been returned in SysEnvRec.
  41288.  
  41289. The MPW 2.0 interface files contain code, or “glue”, for System file versions earlier
  41290. than 4.1, as well as for the 64K and the Macintosh XL ROMs.  The glue checks for the
  41291. existence of the trap at runtime; if the call does not exist, the glue fills in all
  41292. fields of the record except systemVersion and returns the result code envNotPresent.
  41293.  
  41294. Assembly-language note:   As with the MoveHHi procedure, assembly-language
  41295.                           programmers using MPW should link with the glue and
  41296.                           execute
  41297.  
  41298.                               JSR SysEnvirons
  41299.  
  41300.                           If you’re using another development system, refer
  41301.                           to its documentation for details.
  41302.  
  41303. The machineType field returns one of the following constants:
  41304.  
  41305. CONST  envMachUnknown  = 0;    {new version of Macintosh--not covered }
  41306.                                { by this version of SysEnvirons}
  41307.        env512KE        = 1;    {Macintosh 512K enhanced}
  41308.        envMacPlus      = 2;    {Macintosh Plus}
  41309.        envSE           = 3;    {Macintosh SE}
  41310.        envMacII        = 4;    {Macintosh II}
  41311.        envMacIIx       = 5;    {Macintosh IIx}
  41312.        envMacIIcx      = 6;    {Macintosh IIcx}
  41313.        envSE30         = 7;    {Macintosh SE/30}
  41314.        envPortable     = 8;    {Macintosh Portable}
  41315.        envMacIIci      = 9;    {Macintosh IIci}
  41316.  
  41317. In addition to these, the glue for SysEnvirons may return one of the following:
  41318.  
  41319. CONST  envMac  = –1;    {Macintosh with 64K ROM}
  41320.        envXL   = –2;    {Macintosh XL}
  41321.  
  41322. The systemVersion field returns the version number of the System file represented as
  41323. two byte-long numbers, separated by a period. (It is not a fixed point number.) For
  41324. instance, System 4.1 returns $0410 or 04.10 in this field.
  41325. (Applications can use this for compare operations.)  If SysEnvirons is called while a
  41326. system earlier than System 4.1 is running, the glue will return a $0 in this field,
  41327. and the result code envNotPresent will be returned.
  41328.  
  41329. The processor field returns one of the following constants:
  41330.  
  41331. CONST  envCPUUnknown  = 0;    {new processor--not yet covered by this }
  41332.                               { version of SysEnvirons}
  41333.        env68000       = 1;    {MC68000 processor}
  41334.        env68010       = 2;    {MC68010 processor}
  41335.        env68020       = 3;    {MC68020 processor}
  41336.        env68030       = 4;    {MC68030 processor}
  41337.  
  41338. The hasFPU field tells whether or not a Motorola MC68881 floating-point coprocessor
  41339. unit is present.  (This field does not apply to third-party memory-mapped coprocessor
  41340. add-ons.)
  41341.  
  41342. The hasColorQD field tells whether or not Color QuickDraw is present.  It does not
  41343. indicate whether or not a color screen is present (high-level QuickDraw calls provide
  41344. this information).
  41345.  
  41346. The keyboardType field returns one of the following constants:
  41347.  
  41348. CONST  envUnknownKbd    = 0;    {Macintosh Plus keyboard with keypad}
  41349.        envMacKbd        = 1;    {Macintosh keyboard}
  41350.        envMacAndPad     = 2;    {Macintosh keyboard and keypad}
  41351.        envMacPlusKbd    = 3;    {Macintosh Plus keyboard}
  41352.        envAExtendKbd    = 4;    {Apple Extended keyboard}
  41353.        envStandADBKbd   = 5;    {Apple Standard keyboard}
  41354.        envPortADBKbd    = 6;    {Macintosh Portable keyboard}
  41355.        envPortISOADBKbd = 7;    {Macintosh Portable keyboard (ISO)}
  41356.        envStdISOADBKbd  = 8;    {Apple Standard keyboard (ISO)}
  41357.        envExtISOADBKbd  = 9;    {Apple Extended keyboard (ISO)}
  41358.  
  41359. If the Apple Desktop Bus™ is in use, this field returns the keyboard type of the
  41360. keyboard on which a keystroke was last made.
  41361.  
  41362. ATDrvrVersNum returns the version number of AppleTalk,  if it’s been loaded
  41363. (that is, if MPPOpen has been called); otherwise, 0 is returned in this field.
  41364.  
  41365. SysVRefNum returns the working directory reference number (or volume reference number)
  41366. of the directory that contains the currently open System file.
  41367.  
  41368. æKY VBLProcPtr
  41369. æFc OSUtils.h
  41370. æT typedef
  41371. æD typedef pascal void (*VBLProcPtr)(void);
  41372. æC 
  41373.  
  41374. æKY VBLTask
  41375. æFc OSUtils.h
  41376. æT struct
  41377. æD struct VBLTask {
  41378.     QElemPtr qLink;
  41379.     short qType;
  41380.     VBLProcPtr vblAddr;
  41381.     short vblCount;
  41382.     short vblPhase;
  41383. };
  41384.  
  41385. typedef struct VBLTask VBLTask;
  41386. /* 
  41387.  
  41388.  */
  41389. æC 
  41390. »ABOUT THE VERTICAL RETRACE MANAGER
  41391. _______________________________________________________________________________
  41392.  
  41393. The Macintosh video circuitry generates a vertical retrace interrupt, also known as
  41394. the vertical blanking (or VBL) interrupt, 60 times a second while the beam of the
  41395. display tube returns from the bottom of the screen to the top to display the next
  41396. frame. This interrupt is used as a convenient time for performing the following
  41397. sequence of recurrent system tasks:
  41398.  
  41399.   1.  Increment the number of ticks since system startup (every interrupt).
  41400.       You can get this number by calling the Toolbox Event Manager function
  41401.       TickCount.
  41402.   2.  Check whether the stack has expanded into the heap; if so, it calls
  41403.       the System Error Handler (every interrupt).
  41404.   3.  Handle cursor movement (every interrupt).
  41405.   4.  Post a mouse event if the state of the mouse button changed from its
  41406.       previous state and then remained unchanged for four interrupts (every
  41407.       other interrupt).
  41408.   5.  Reset the keyboard if it’s been reattached after having been detached
  41409.       (every 32 interrupts).
  41410.   6.  Post a disk-inserted event if the user has inserted a disk or taken
  41411.       any other action that requires a volume to be mounted (every 30
  41412.       interrupts).
  41413.  
  41414. These tasks must execute at regular intervals based on the “heartbeat” of the Macintosh,
  41415. and shouldn’t be changed.
  41416.  
  41417. Tasks performed during the vertical retrace interrupt are known as VBL tasks. An
  41418. application can add any number of its own VBL tasks for the Vertical Retrace Manager
  41419. to execute. VBL tasks can be set to execute at any frequency (up to once per vertical
  41420. retrace interrupt). For example, an electronic mail application might add a VBL task
  41421. that checks every tenth of a second (every six interrupts) to see if it has received
  41422. any messages. These tasks can perform any desired action as long as they don’t make
  41423. any calls to the Memory Manager, directly or indirectly, and don’t depend on handles
  41424. to unlocked blocks being valid. They must preserve all registers other than A0-A3 and
  41425. D0-D3. If they use application globals, they must also ensure that register A5 contains
  41426. the address of the boundary between the application globals and the application
  41427. parameters; for details, see SetCurrentA5 and SetA5 in Macintosh Technical Note
  41428. #208.
  41429.  
  41430. •••Refer to Technical Note #208:•••
  41431.  
  41432. Warning:  When interrupts are disabled (such as during a disk access), or
  41433.           when VBL tasks take longer than about a sixtieth of a second to
  41434.           perform, one or more vertical retrace interrupts may be missed,
  41435.           thereby affecting the performance of certain VBL tasks. For
  41436.           instance, while a disk is being accessed, the updating of the
  41437.           cursor movement may be irregular.
  41438.  
  41439. Note:  To perform periodic actions that do allocate and release memory, you
  41440.        can use the Desk Manager procedure SystemTask. Or, since the first
  41441.        thing the Vertical Retrace Manager does during a vertical retrace
  41442.        interrupt is increment the tick count, you can call TickCount
  41443.        repeatedly and perform periodic actions whenever a specific number
  41444.        of ticks have elapsed.
  41445.  
  41446. Information describing each VBL task is contained in the vertical retrace queue. The
  41447. vertical retrace queue is a standard Macintosh Operating System queue, as described
  41448. in the Operating System Utilities chapter. Each entry in the vertical retrace queue
  41449. has the following structure:
  41450.  
  41451. TYPE  VBLTask = RECORD
  41452.                   qLink:     QElemPtr;  {next queue entry}
  41453.                   qType:     INTEGER;   {queue type}
  41454.                   vblAddr:   ProcPtr;   {pointer to task}
  41455.                   vblCount:  INTEGER;   {task frequency}
  41456.                   vblPhase:  INTEGER    {task phase}
  41457.                 END;
  41458.  
  41459. QLink points to the next entry in the queue, and qType indicates the queue type,
  41460. which must be ORD(vType).
  41461.  
  41462. VBLAddr contains a pointer to the task. VBLCount specifies the number of ticks between
  41463. successive calls to the task. This value is decremented each sixtieth of a second
  41464. until it reaches 0, at which point the task is called. The task must then reset
  41465. vblCount, or its entry will be removed from the queue after it has been executed.
  41466. VBLPhase contains an integer (smaller than vblCount) used to modify vblCount when the
  41467. task is first added to the queue. This ensures that two or more tasks added to the
  41468. queue at the same time with the same vblCount value will be out of phase with each
  41469. other, and won’t be called during the same interrupt. Unless there are many tasks to
  41470. be added to the queue at the same time, vblPhase can usually be set to 0.
  41471.  
  41472. The Vertical Retrace Manager uses bit 6 of the queue flags field in the queue header
  41473. to indicate when a task is being executed:
  41474.  
  41475.   Bit    Meaning
  41476.    6     Set if a task is being executed
  41477.  
  41478. Assembly-language note:  Assembly-programmers can use the global constant
  41479.                          inVBL to test this bit.
  41480.  
  41481.  
  41482. æKY GetSysPPtr
  41483. æFc OSUtils.h
  41484. æT Function
  41485. æD pascal SysPPtr GetSysPPtr(void); 
  41486. æDT SysPPtr myVariable = GetSysPPtr()(void);
  41487. æRI II-381
  41488. æC  
  41489. [Not in ROM]
  41490.  
  41491. GetSysPPtr returns a pointer to the low-memory copy of parameter RAM. You can examine
  41492. the values stored in its various fields, or change them before calling WriteParam
  41493. (below).
  41494.  
  41495. Assembly-language note:  Assembly-language programmers can simply access the
  41496.                          global variables corresponding to the low-memory copy
  41497.                          of parameter RAM. These variables, which begin at the
  41498.                          address SysParam, are listed in the summary.
  41499.  
  41500. æKY SysBeep
  41501. æFc OSUtils.h
  41502. æT Function
  41503. æTN A9C8
  41504. æD pascal void SysBeep(short duration)
  41505.     = 0xA9C8; 
  41506. æDT SysBeep((short) duration);
  41507. æMM
  41508. æRI II-385, V-592
  41509. æC  
  41510. SysBeep causes the system to beep for approximately the number of ticks specified by
  41511. the duration parameter. The sound decays from loud to soft; after about five seconds
  41512. it’s inaudible. The initial volume of the beep depends on the current speaker volume
  41513. setting, which the user can adjust with the Control Panel desk accessory. If the
  41514. speaker volume has been set to 0 (silent), SysBeep instead causes the menu bar to
  41515. blink once.
  41516.  
  41517. Assembly-language note:  Unlike all other Operating System Utilities, this
  41518.                          procedure is stack-based.
  41519.  
  41520. æKY KeyTrans
  41521. æFc OSUtils.h
  41522. æT Function
  41523. æTN A9C3
  41524. æD pascal long KeyTrans(Ptr transData,short keycode,long *state)
  41525.     = 0xA9C3; 
  41526. æDT long myVariable = KeyTrans((Ptr) transData,(short) keycode,(long *) state);
  41527. æRT 160
  41528. æRI V-195, N160
  41529. æC 
  41530. [256K ROM]
  41531.  
  41532. KeyTrans lets your application convert key codes to ASCII values as determined by a
  41533. 'KCHR' resource.  The 'KCHR' resource type is discussed in the Resource Manager
  41534. chapter.
  41535.  
  41536. TransData points to a 'KCHR' resource, which maps virtual key codes to ASCII values. 
  41537. The keycode parameter is a 16-bit value with the structure shown in Figure 9.
  41538.  
  41539. •••Refer to Figure 9.•••
  41540.  
  41541. Figure 9–Keycode Parameter Structure
  41542.  
  41543. The state parameter is a value maintained by the Toolbox.  Your application should
  41544. save it between calls to KeyTrans.  If your application changes transData to point to
  41545. a different 'KCHR' resource, it should reset the state value to 0.
  41546.  
  41547. KeyTrans returns a 32-bit value with the structure shown in Figure 10.  In this
  41548. structure, ASCII 1 is the ASCII value of the first character generated by the key
  41549. code parameter; reserved1 is an extension for future “16-bit ASCII” coding.  ASCII 2
  41550. and reserved2 have the same meanings for a possible second character generated by key
  41551. code—for example, if key code designates an alphabetic character with a separate
  41552. accent character.
  41553.  
  41554. •••Refer to Figure 10.•••
  41555.  
  41556. Figure 10–KeyTrans Return Structure
  41557.  
  41558. Assembly-language note:  The macro you invoke to call KeyTrans from assembly
  41559.                          language is named _KeyTrans. Its parameters are
  41560.                          passed on the stack.
  41561.  
  41562. æKY DTInstall
  41563. æFc OSUtils.h
  41564. æT Function
  41565. æD pascal OSErr DTInstall(QElemPtr dtTaskPtr); 
  41566. æDT OSErr myVariable = DTInstall((QElemPtr) dtTaskPtr);
  41567. æRI V-467
  41568. æC _____________________________________________________________________________________
  41569.  
  41570. Trap macro  _DTInstall
  41571.  
  41572. On entry  A0:  dtTaskPtr (pointer)
  41573.  
  41574. On exit   D0:  result code (word) 
  41575.  
  41576. Note:  
  41577.  
  41578.     To reduce overhead at interrupt time, instead of executing the 
  41579.     _DTInstall trap you can load the jump vector jDTInstall into an address 
  41580.     register other than A0 and execute a JSR instruction using that register. 
  41581. _____________________________________________________________________________________
  41582.  
  41583. DTInstall adds the specified task to the deferred task queue. 
  41584.  
  41585. Your application must fill in all fields of the task except qLink. 
  41586.  
  41587. DTInstall returns one of the result codes listed below.
  41588.  
  41589. Result codes
  41590.  
  41591.   noErr    No error
  41592.   vTypErr  Invalid queue element 
  41593.  
  41594. æKY GetMMUMode
  41595. æFc OSUtils.h
  41596. æT Function
  41597. æD pascal char GetMMUMode(void); 
  41598. æDT char myVariable = GetMMUMode()(void);
  41599. æRT 228
  41600. æRI V-592
  41601. æC 
  41602. [Not in ROM]
  41603.  
  41604. GetMMUMode returns the address translation mode currently in use.
  41605.  
  41606. Assembly-language note:  Assembly-language programmers can determine the
  41607.                          current address mode by testing the contents of
  41608.                          the global variable MMU32Bit; it’s TRUE if 32-bit
  41609.                          mode is in effect.
  41610.  
  41611. •••Refer to Technical Note #228:•••
  41612.  
  41613. æKY SwapMMUMode
  41614. æFc OSUtils.h
  41615. æT Function
  41616. æD pascal void SwapMMUMode(char *mode); 
  41617. æDT SwapMMUMode((char *) mode);
  41618. æRI V-593, C1-6
  41619. æC 
  41620. Trap macro  _SwapMMUMode
  41621. On entry    D0:  mode (byte)
  41622. On exit     D0:  mode (byte)
  41623.  
  41624. SwapMMUMode sets the address translation mode to that specified by the mode parameter.
  41625.  The mode in use prior to the call is returned in mode, and can be restored with
  41626. another call to SwapMMUMode.
  41627.  
  41628. æKY SysEnvirons
  41629. æFc OSUtils.h
  41630. æT Function
  41631. æD pascal OSErr SysEnvirons(short versionRequested,SysEnvRec *theWorld); 
  41632. æDT OSErr myVariable = SysEnvirons((short) versionRequested,(SysEnvRec *) theWorld);
  41633. æRT 67, 103, 156, 184, 190,  207,212
  41634. æRI V-5, N129, N156
  41635. æC 
  41636. ———————————————————————————————————————————————————————————————————————————————
  41637. »DETERMINING THE FEATURES OF A MACHINE                  CompatibilityGuide
  41638. _______________________________________________________________________________
  41639.  
  41640. As the Macintosh family grows, applications need a reliable and comprehensive way of
  41641. determining what software and hardware features are available on a given machine. 
  41642. Although the Operating System Utilities routine Environs indicates the type of machine
  41643. and ROM version running, it provides no help in distinguishing between the plethora
  41644. of different software feature sets and hardware configurations that an application
  41645. may encounter.
  41646.  
  41647. A new function, SysEnvirons, provides detailed information about what software functionality
  41648. (Color QuickDraw, as an example) is available, as well as what hardware devices
  41649. (processors, peripherals, and so on) are installed or connected.
  41650.  
  41651. All of the Toolbox Managers must be initialized before calling SysEnvirons.
  41652. In addition, the AppleTalk Manager routine MPPOpen must be called if the driver
  41653. version information in atDrvrVersNum is desired.  SysEnvirons is not intended for use
  41654. by device drivers, but can be called from desk accessories. (It does not assume that
  41655. register A5 has been properly set up.)
  41656.  
  41657. FUNCTION SysEnvirons (versionReqested: INTEGER;
  41658.                       VAR theWorld: SysEnvRec) : OSErr;  [Not in ROM]
  41659.  
  41660. •••Refer to Technical Note #129:•••
  41661.  
  41662. Trap macro    _SysEnvirons
  41663. On entry    A0:  sysEnvRec (pointer)
  41664.             D0:  versReqested (word)
  41665. On exit     A0:  sysEnvRec (pointer)
  41666.             D0:  result code (word)
  41667.  
  41668. Result codes    noErr            No error
  41669.                 envNotPresent    SysEnvirons trap not present
  41670.                 envBadVers       Nonpositive version number passed
  41671.                 envVersTooBig    Requested version of SysEnvirons
  41672.                                  call not available
  41673.  
  41674. In theWorld, SysEnvirons returns a system environment record describing the features
  41675. of the machine.  Designed to be extendible, SysEnvirons will be updated as new features
  41676. are added, and the system environment record that’s returned will be expanded. 
  41677. System File 4.1 contains version 1 of SysEnvirons; subsequent versions will be incremented
  41678. by 1.
  41679.  
  41680. The system environment record for version 1 of SysEnvirons contains the following
  41681. fields:
  41682.  
  41683. TYPE  SysEnvRec = RECORD
  41684.                     environsVersion:  INTEGER;
  41685.                     machineType:      INTEGER;
  41686.                     systemVersion:    INTEGER;
  41687.                     processor:        INTEGER;
  41688.                     hasFPU:           BOOLEAN;
  41689.                     hasColorQD:       BOOLEAN;
  41690.                     keyBoardType:     INTEGER;
  41691.                     atDrvrVersNum:    INTEGER;
  41692.                     sysVRefNum:       INTEGER
  41693.                   END;
  41694.  
  41695. New versions of the call will add fields to this record.  To distinguish between
  41696. different versions of the call, and thereby between the different sizes of records
  41697. they return, SysEnvirons returns its version number in the environsVersion field.  If
  41698. you request version 2, for instance, but only version 1 is available, the environsVersion
  41699. field will contain the value 1, and the result code envVersTooBig will be returned. 
  41700. This tells you that only the information for version 1 has been returned in SysEnvRec.
  41701.  
  41702. The MPW 2.0 interface files contain code, or “glue”, for System file versions earlier
  41703. than 4.1, as well as for the 64K and the Macintosh XL ROMs.  The glue checks for the
  41704. existence of the trap at runtime; if the call does not exist, the glue fills in all
  41705. fields of the record except systemVersion and returns the result code envNotPresent.
  41706.  
  41707. Assembly-language note:   As with the MoveHHi procedure, assembly-language
  41708.                           programmers using MPW should link with the glue and
  41709.                           execute
  41710.  
  41711.                               JSR SysEnvirons
  41712.  
  41713.                           If you’re using another development system, refer
  41714.                           to its documentation for details.
  41715.  
  41716. The machineType field returns one of the following constants:
  41717.  
  41718. CONST  envMachUnknown  = 0;    {new version of Macintosh--not covered }
  41719.                                { by this version of SysEnvirons}
  41720.        env512KE        = 1;    {Macintosh 512K enhanced}
  41721.        envMacPlus      = 2;    {Macintosh Plus}
  41722.        envSE           = 3;    {Macintosh SE}
  41723.        envMacII        = 4;    {Macintosh II}
  41724.        envMacIIx       = 5;    {Macintosh IIx}
  41725.        envMacIIcx      = 6;    {Macintosh IIcx}
  41726.        envSE30         = 7;    {Macintosh SE/30}
  41727.        envPortable     = 8;    {Macintosh Portable}
  41728.        envMacIIci      = 9;    {Macintosh IIci}
  41729.  
  41730. In addition to these, the glue for SysEnvirons may return one of the following:
  41731.  
  41732. CONST  envMac  = –1;    {Macintosh with 64K ROM}
  41733.        envXL   = –2;    {Macintosh XL}
  41734.  
  41735. The systemVersion field returns the version number of the System file represented as
  41736. two byte-long numbers, separated by a period. (It is not a fixed point number.) For
  41737. instance, System 4.1 returns $0410 or 04.10 in this field.
  41738. (Applications can use this for compare operations.)  If SysEnvirons is called while a
  41739. system earlier than System 4.1 is running, the glue will return a $0 in this field,
  41740. and the result code envNotPresent will be returned.
  41741.  
  41742. The processor field returns one of the following constants:
  41743.  
  41744. CONST  envCPUUnknown  = 0;    {new processor--not yet covered by this }
  41745.                               { version of SysEnvirons}
  41746.        env68000       = 1;    {MC68000 processor}
  41747.        env68010       = 2;    {MC68010 processor}
  41748.        env68020       = 3;    {MC68020 processor}
  41749.        env68030       = 4;    {MC68030 processor}
  41750.  
  41751. The hasFPU field tells whether or not a Motorola MC68881 floating-point coprocessor
  41752. unit is present.  (This field does not apply to third-party memory-mapped coprocessor
  41753. add-ons.)
  41754.  
  41755. The hasColorQD field tells whether or not Color QuickDraw is present.  It does not
  41756. indicate whether or not a color screen is present (high-level QuickDraw calls provide
  41757. this information).
  41758.  
  41759. The keyboardType field returns one of the following constants:
  41760.  
  41761. CONST  envUnknownKbd    = 0;    {Macintosh Plus keyboard with keypad}
  41762.        envMacKbd        = 1;    {Macintosh keyboard}
  41763.        envMacAndPad     = 2;    {Macintosh keyboard and keypad}
  41764.        envMacPlusKbd    = 3;    {Macintosh Plus keyboard}
  41765.        envAExtendKbd    = 4;    {Apple Extended keyboard}
  41766.        envStandADBKbd   = 5;    {Apple Standard keyboard}
  41767.        envPortADBKbd    = 6;    {Macintosh Portable keyboard}
  41768.        envPortISOADBKbd = 7;    {Macintosh Portable keyboard (ISO)}
  41769.        envStdISOADBKbd  = 8;    {Apple Standard keyboard (ISO)}
  41770.        envExtISOADBKbd  = 9;    {Apple Extended keyboard (ISO)}
  41771.  
  41772. If the Apple Desktop Bus™ is in use, this field returns the keyboard type of the
  41773. keyboard on which a keystroke was last made.
  41774.  
  41775. ATDrvrVersNum returns the version number of AppleTalk,  if it’s been loaded
  41776. (that is, if MPPOpen has been called); otherwise, 0 is returned in this field.
  41777.  
  41778. SysVRefNum returns the working directory reference number (or volume reference number)
  41779. of the directory that contains the currently open System file.
  41780.  
  41781. _______________________________________________________________________________
  41782.  
  41783. æKY ReadDateTime
  41784. æFc OSUtils.h
  41785. æT Function
  41786. æD pascal OSErr ReadDateTime(unsigned long *time); 
  41787. æDT OSErr myVariable = ReadDateTime((unsigned long *) time);
  41788. æRI II-378
  41789. æC 
  41790. Trap macro  _ReadDateTime
  41791. On entry    A0:  pointer to long word secs
  41792. On exit     A0:  pointer to long word secs
  41793.             D0:  result code (word)
  41794.  
  41795. ReadDateTime copies the date and time stored in the clock chip to a low-memory location
  41796. and returns it in the secs parameter. This routine is called at system startup;
  41797. you’ll probably never need to call it yourself. Instead you’ll call GetDateTime (see
  41798. below).
  41799.  
  41800. Assembly-language note:  The low-memory location to which ReadDateTime
  41801.                          copies the date and time is the global variable Time.
  41802.  
  41803. Result codes    noErr       No error
  41804.                 clkRdErr    Unable to read clock
  41805.  
  41806. æKY GetDateTime
  41807. æFc OSUtils.h
  41808. æT Function
  41809. æD pascal void GetDateTime(unsigned long *secs); 
  41810. æDT GetDateTime((unsigned long *) secs);
  41811. æRI II-378
  41812. æC 
  41813. GetDateTime returns in the secs parameter the contents of the low-memory location in
  41814. which the date and time setting is stored; if this setting reflects the actual current
  41815. date and time, secs will contain the number of seconds between midnight, January 1,
  41816. 1904 and the time that the function was called.
  41817.  
  41818. Note:  If your application disables interrupts for longer than a second,
  41819.        the number of seconds returned will not be exact.
  41820.  
  41821. Assembly-language note:  Assembly-language programmers can just access
  41822.                          the global variable Time.
  41823.  
  41824. If you wish, you can convert the value returned by GetDateTime to a date/time record
  41825. by calling the Secs2Date procedure.
  41826.  
  41827. Note:  Passing the value returned by GetDateTime to the International
  41828.        Utilities Package procedure IUDateString or IUTimeString will yield
  41829.        a string representing the corresponding date or time of day,
  41830.        respectively.
  41831.  
  41832. æKY SetDateTime
  41833. æFc OSUtils.h
  41834. æT Function
  41835. æD pascal OSErr SetDateTime(unsigned long time); 
  41836. æDT OSErr myVariable = SetDateTime((unsigned long) time);
  41837. æRI II-379
  41838. æC 
  41839. Trap macro  _SetDateTime
  41840. On entry    D0:  secs (long word)
  41841. On exit     D0:  result code (word)
  41842.  
  41843. SetDateTime takes a number of seconds since midnight, January 1, 1904, as specified
  41844. by the secs parameter, and writes it to the clock chip as the current date and time.
  41845. It then attempts to read the value just written and verify it by comparing it to the
  41846. secs parameter.
  41847.  
  41848. Assembly-language note:  SetDateTime updates the global variable Time to
  41849.                          the value of the secs parameter.
  41850.  
  41851. Result codes    noErr       No error
  41852.                 clkWrErr    Time written did not verify
  41853.                 clkRdErr    Unable to read clock
  41854.  
  41855. æKY SetTime
  41856. æFc OSUtils.h
  41857. æT Function
  41858. æD pascal void SetTime(const DateTimeRec *d); 
  41859. æDT SetTime((const DateTimeRec *) d);
  41860. æRI II-380
  41861. æC  
  41862. SetTime takes the date and time specified by the date parameter, converts it into the
  41863. corresponding number of seconds elapsed since midnight, January 1, 1904 (by calling
  41864. Date2Secs), and then writes that value to the clock chip as the current date and time
  41865. (by calling SetDateTime).
  41866.  
  41867. Assembly-language note:  From assembly language, you can just call Date2Secs
  41868.                          and SetDateTime directly.
  41869.  
  41870. æKY GetTime
  41871. æFc OSUtils.h
  41872. æT Function
  41873. æD pascal void GetTime(DateTimeRec *d); 
  41874. æDT GetTime((DateTimeRec *) d);
  41875. æRI II-380
  41876. æC  
  41877. GetTime takes the number of seconds elapsed since midnight, January 1, 1904
  41878. (obtained by calling GetDateTime), converts that value into a date and time (by
  41879. calling Secs2Date), and returns the result in the date parameter.
  41880.  
  41881. Assembly-language note:  From assembly language, you can pass the value
  41882.                          of the global variable Time to Secs2Date.
  41883.  
  41884. æKY Date2Secs
  41885. æFc OSUtils.h
  41886. æT Function
  41887. æD pascal void Date2Secs(const DateTimeRec *d,unsigned long *s); 
  41888. æDT Date2Secs((const DateTimeRec *) d,(unsigned long *) s);
  41889. æRI II-379
  41890. æC 
  41891. Trap macro  _Date2Secs
  41892. On entry    A0:  pointer to date/time record
  41893. On exit     D0:  secs (long word)
  41894.  
  41895. Date2Secs takes the given date/time record, converts it to the corresponding number
  41896. of seconds elapsed since midnight, January 1, 1904, and returns the result in the
  41897. secs parameter. The dayOfWeek field of the date/time record is ignored. The values
  41898. passed in the year and month fields should be within their allowable ranges, or
  41899. unpredictable results will occur. The remaining four fields of the date/time record
  41900. may contain any value. For example, September 34 will be interpreted as October 4,
  41901. and you could specify the 300th day of the year as January 300.
  41902.  
  41903. æKY Secs2Date
  41904. æFc OSUtils.h
  41905. æT Function
  41906. æD pascal void Secs2Date(unsigned long s,DateTimeRec *d); 
  41907. æDT Secs2Date((unsigned long) s,(DateTimeRec *) d);
  41908. æRI II-380
  41909. æC 
  41910. Trap macro  _Secs2Date
  41911. On entry    D0:  secs (long word)
  41912. On exit     A0:  pointer to date/time record
  41913.  
  41914. Secs2Date takes a number of seconds elapsed since midnight, January 1, 1904 as specified
  41915. by the secs parameter, converts it to the corresponding date and time, and returns
  41916. the corresponding date/time record in the date parameter.
  41917.  
  41918. æKY Delay
  41919. æFc OSUtils.h
  41920. æT Function
  41921. æD pascal void Delay(long numTicks,long *finalTicks); 
  41922. æDT Delay((long) numTicks,(long *) finalTicks);
  41923. æRT 2
  41924. æRI II-384
  41925. æC 
  41926. Trap macro  _Delay
  41927. On entry    A0:  numTicks (long word)
  41928. On exit     D0:  finalTicks (long word)
  41929.  
  41930. Delay causes the system to wait for the number of ticks (sixtieths of a second)
  41931. specified by numTicks, and returns in finalTicks the total number of ticks from
  41932. system startup to the end of the delay.
  41933.  
  41934. Warning:  Don’t rely on the duration of the delay being exact; it will usually
  41935.           be accurate to within one tick, but may be off by more than that.
  41936.           The Delay procedure enables all interrupts and checks the tick count
  41937.           that’s incremented during the vertical retrace interrupt; however,
  41938.           it’s possible for this interrupt to be disabled by other interrupts,
  41939.           in which case the duration of the delay will not be exactly what you
  41940.           requested.
  41941.  
  41942. Assembly-language note:  On exit from this procedure, register D0 contains the
  41943.                          value of the global variable Ticks as measured at the
  41944.                          end of the delay.
  41945.  
  41946. æKY GetTrapAddress
  41947. æFc OSUtils.h
  41948. æT Function
  41949. æD pascal long GetTrapAddress(short trapNum); 
  41950. æDT long myVariable = GetTrapAddress((short) trapNum);
  41951. æRT 2
  41952. æRI II-384, IV-234, N2-4
  41953. æC 
  41954. Trap macro  _GetTrapAddress
  41955. On entry    D0:  trapNum (word)
  41956. On exit     A0:  address of routine
  41957.  
  41958. GetTrapAddress returns the address of a routine currently installed in the trap
  41959. dispatch table under the trap number designated by trapNum. To find out the trap
  41960. number for a particular routine, see Appendix C.
  41961.  
  41962. Assembly-language note:  When you use this technique to bypass the trap
  41963.                          dispatcher, you don’t get the extra level of register
  41964.                          saving. The routine itself will preserve A2-A6 and
  41965.                          D3-D7, but if you want any other registers preserved
  41966.                          across the call you have to save and restore them
  41967.                          yourself.
  41968.  
  41969. æKY SetTrapAddress
  41970. æFc OSUtils.h
  41971. æT Function
  41972. æD pascal void SetTrapAddress(long trapAddr,short trapNum); 
  41973. æDT SetTrapAddress((long) trapAddr,(short) trapNum);
  41974. æRT 2
  41975. æRI II-384, IV-234, N2-4
  41976. æC 
  41977. Trap macro  _SetTrapAddress
  41978. On entry    A0:  trapAddr (address)
  41979.             D0:  trapNum (word)
  41980.  
  41981. SetTrapAddress installs in the trap dispatch table a routine whose address is trapAddr;
  41982. this routine is installed under the trap number designated by trapNum.
  41983.  
  41984. Warning:  Since the trap dispatch table can address locations within a range
  41985.           of only 64K bytes from the beginning of the system heap, the routine
  41986.           you install should be in the system heap.
  41987.  
  41988. Assembly-language note:  To use GetTrapAddress and SetTrapAddress with
  41989.                          128K ROM routines, set bit 9 of the trap word to
  41990.                          indicate the new trap numbering. The state of bit
  41991.                          10 then determines whether the intended trap is a
  41992.                          Toolbox or Operating System trap. You can set these
  41993.                          two bits with the arguments NEWOS and NEWTOOL.
  41994.  
  41995.                          Of course, the 64K ROM versions of GetTrapAddress and
  41996.                          SetTrapAddress will fail if applied to traps that
  41997.                          exist only in the 128K ROM.
  41998.  
  41999.                          The NGetTrapAddress and NSetTrapAddress routines list
  42000.                          the possible permutations of arguments. (The syntax
  42001.                          shown applies to the Lisa Workshop Assembler;
  42002.                          programmers using another development system should
  42003.                          consult its documentation for the proper syntax.)
  42004.  
  42005. æKY NGetTrapAddress
  42006. æFc OSUtils.h
  42007. æT Function
  42008. æD pascal long NGetTrapAddress(short trapNum,TrapType tTyp); 
  42009. æDT long myVariable = NGetTrapAddress((short) trapNum,(TrapType) tTyp);
  42010. æRT 156, 212
  42011. æRI IV-234, N156-3
  42012. æC  
  42013. [Not in ROM]
  42014.  
  42015. NGetTrapAddress is identical to GetTrapAddress except that it requires you to specify
  42016. in tType whether the given routine is an Operating System or a Toolbox trap.
  42017.  
  42018. Trap macro  _GetTrapAddress ,NEWOS    (bit 9 set, bit 10 clear)
  42019.             _GetTrapAddress ,NEWTOOL  (bit 9 set, bit 10 set) 
  42020. On entry    D0:  trapNum (word)
  42021. On exit     A0:  address of routine
  42022.  
  42023. æKY NSetTrapAddress
  42024. æFc OSUtils.h
  42025. æT Function
  42026. æD pascal void NSetTrapAddress(long trapAddr,short trapNum,TrapType tTyp); 
  42027. æDT NSetTrapAddress((long) trapAddr,(short) trapNum,(TrapType) tTyp);
  42028. æRI IV-234
  42029. æC  
  42030. [Not in ROM]
  42031.  
  42032. NSetTrapAddress is identical to SetTrapAddress except that it requires you to specify
  42033. in tType whether the given routine is an Operating System or a Toolbox trap.
  42034.  
  42035. Trap macro  _SetTrapAddress ,NEWOS    (bit 9 set, bit 10 clear)
  42036.             _SetTrapAddress ,NEWTOOL  (bit 9 set, bit 10 set)
  42037. On entry    A0:  trapAddr (address)
  42038.             D0:  trapNum (word)
  42039.             
  42040.  
  42041. æKY WriteParam
  42042. æFc OSUtils.h
  42043. æT Function
  42044. æD pascal OSErr WriteParam(void); 
  42045. æDT OSErr myVariable = WriteParam()(void);
  42046. æRI II-382
  42047. æC 
  42048. Trap macro  _WriteParam
  42049. On entry    A0:    SysParam (pointer)
  42050.             D0:    MinusOne (long word)
  42051.                    (You have to pass the values of these global variables for
  42052.                    historical reasons.)
  42053. On exit     D0:    result code (word)
  42054.  
  42055. WriteParam writes the low-memory copy of parameter RAM to the clock chip. You should
  42056. previously have called GetSysPPtr and changed selected values as desired.
  42057.  
  42058. WriteParam also attempts to verify the values written by reading them back in and
  42059. comparing them to the values in the low-memory copy.
  42060.  
  42061. Note:  If you’ve accidentally written incorrect values into parameter RAM,
  42062.        the system may not be able to start up. If this happens, you can reset
  42063.        parameter RAM by removing the battery, letting the Macintosh sit turned
  42064.        off for about five minutes, and then putting the battery back in.
  42065.  
  42066. Result codes    noErr      No error
  42067.                 prWrErr    Parameter RAM written did not verify
  42068.  
  42069. æKY EqualString
  42070. æFc OSUtils.h
  42071. æT Function
  42072. æD pascal Boolean EqualString(const Str255 str1,const Str255 str2,Boolean caseSens,
  42073.     Boolean diacSens); 
  42074. æDT Boolean myVariable = EqualString((const Str255) str1,(const Str255) str2,(Boolean) caseSens,()
  42075.     Boolean diacSens);
  42076. æRI II-377
  42077. æC 
  42078. Assembly-language note:  The trap macros for these utility routines have
  42079.                          optional arguments corresponding to the Pascal flags
  42080.                          passed to the routines. When present, such an argument
  42081.                          sets a certain bit of the routine trap word; this is
  42082.                          equivalent to setting the corresponding Pascal flag to
  42083.                          either TRUE or FALSE, depending on the flag. The trap
  42084.                          macros for these routines are listed with all the
  42085.                          possible permutations of arguments. Whichever
  42086.                          permutation you use, you must type it exactly as shown.
  42087.                          (The syntax shown applies to the Lisa Workshop
  42088.                          Assembler; programmers using another development
  42089.                          system should consult its documentation for the proper
  42090.                          syntax.)
  42091.  
  42092.  
  42093. Trap macro  _CmpString
  42094.             _CmpString ,MARKS       (sets bit 9, for diacSens=FALSE)
  42095.             _CmpString ,CASE        (sets bit 10, for caseSens=TRUE)
  42096.             _CmpString ,MARKS,CASE  (sets bits 9 and 10)
  42097. On entry    A0:    pointer to first character of first string
  42098.             A1:    pointer to first character of second string
  42099.             D0:    high-order word:  length of first string
  42100.                    low-order word:  length of second string
  42101. On exit     D0:    0 if strings equal, 1 if strings not equal (long word)
  42102.  
  42103. EqualString compares the two given strings for equality on the basis of their ASCII
  42104. values. If caseSens is TRUE, uppercase characters are distinguished from the corresponding
  42105. lowercase characters. If diacSens is FALSE, diacritical marks are ignored during the
  42106. comparison. The function returns TRUE if the strings are equal.
  42107.  
  42108. Note:  See also the International Utilities Package function IUEqualString.
  42109.  
  42110. æKY equalstring
  42111. æFc OSUtils.h
  42112. æT Function
  42113. æD Boolean equalstring(char *str1,char *str2,Boolean caseSens,Boolean diacSens); 
  42114. æDT Boolean myVariable = equalstring((char *) str1,(char *) str2,(Boolean) caseSens,(Boolean) diacSens);
  42115. æC 
  42116.  
  42117. æKY UprString
  42118. æFc OSUtils.h
  42119. æT Function
  42120. æD pascal void UprString(Str255 theString,Boolean diacSens); 
  42121. æDT UprString((Str255) theString,(Boolean) diacSens);
  42122. æRI II-377
  42123. æC 
  42124. Assembly-language note:  The trap macros for these utility routines have
  42125.                          optional arguments corresponding to the Pascal flags
  42126.                          passed to the routines. When present, such an argument
  42127.                          sets a certain bit of the routine trap word; this is
  42128.                          equivalent to setting the corresponding Pascal flag to
  42129.                          either TRUE or FALSE, depending on the flag. The trap
  42130.                          macros for these routines are listed with all the
  42131.                          possible permutations of arguments. Whichever
  42132.                          permutation you use, you must type it exactly as shown.
  42133.                          (The syntax shown applies to the Lisa Workshop
  42134.                          Assembler; programmers using another development
  42135.                          system should consult its documentation for the proper
  42136.                          syntax.)
  42137.  
  42138. Trap macro  _UprString
  42139.             _UprString ,MARKS (sets bit 9, for diacSens=FALSE)
  42140. On entry    A0:  pointer to first character of string
  42141.             D0:  length of string (word)
  42142. On exit     A0:  pointer to first character of string
  42143.  
  42144. UprString converts any lowercase letters in the given string to uppercase, returning
  42145. the converted string in theString. In addition, diacritical marks are stripped from
  42146. the string if diacSens is FALSE.
  42147.  
  42148. æKY uprstring
  42149. æFc OSUtils.h
  42150. æT Function
  42151. æD void uprstring(char *theString,Boolean diacSens); 
  42152. æDT uprstring((char *) theString,(Boolean) diacSens);
  42153. æC 
  42154.  
  42155. æKY Enqueue
  42156. æFc OSUtils.h
  42157. æT Function
  42158. æD pascal void Enqueue(QElemPtr qElement,QHdrPtr qHeader); 
  42159. æDT Enqueue((QElemPtr) qElement,(QHdrPtr) qHeader);
  42160. æRI II-382
  42161. æC 
  42162. Trap macro  _Enqueue
  42163. On entry    A0:  qEntry (pointer)
  42164.             A1:  theQueue (pointer)
  42165. On exit     A1:  theQueue (pointer)
  42166.  
  42167. Enqueue adds the queue entry pointed to by qEntry to the end of the queue specified
  42168. by theQueue.
  42169.  
  42170. Note:  Interrupts are disabled for a short time while the queue is updated.
  42171.  
  42172. æKY Dequeue
  42173. æFc OSUtils.h
  42174. æT Function
  42175. æD pascal OSErr Dequeue(QElemPtr qElement,QHdrPtr qHeader); 
  42176. æDT OSErr myVariable = Dequeue((QElemPtr) qElement,(QHdrPtr) qHeader);
  42177. æRI II-383
  42178. æC 
  42179. Trap macro  _Dequeue
  42180. On entry    A0:  qEntry (pointer)
  42181.             A1:  theQueue (pointer)
  42182. On exit     A1:  theQueue (pointer)
  42183.             D0:  result code (word)
  42184.  
  42185. Dequeue removes the queue entry pointed to by qEntry from the queue specified by
  42186. theQueue (without deallocating the entry) and adjusts other entries in the queue
  42187. accordingly.
  42188.  
  42189. Note:  The note under Enqueue above also applies here. In this case, the
  42190.        amount of time interrupts are disabled depends on the length of the
  42191.        queue and the position of the entry in the queue.
  42192.  
  42193. Note:  To remove all entries from a queue, you can just clear all the fields
  42194.        of the queue’s header.
  42195.  
  42196. Result codes    noErr    No error
  42197.                 qErr     Entry not in specified queue
  42198.  
  42199. æKY SetCurrentA5
  42200. æFc OSUtils.h
  42201. æT Function
  42202. æD pascal long SetCurrentA5(void)
  42203.     = {0x2E8D,0x2A78,0x0904}; 
  42204. æDT long myVariable = SetCurrentA5()(void);
  42205. æRT 208
  42206. æRI VI
  42207. æC 
  42208. You can use the functions SetCurrentA5 and SetA5 to save and restore your
  42209. application’s A5 world. Use SetCurrentA5 to get the current value of the system
  42210. global variable CurrentA5.
  42211.  
  42212. The SetCurrentA5 function does two things: first it gets the application’s A5
  42213. and saves it in a variable, then it sets register A5 to the value of the
  42214. application’s low memory global variable CurrentA5.
  42215.  
  42216. Note:  If you are using MPW Version 3.0 or later, you do not need to be
  42217. concerned with the information in this section.
  42218.   
  42219. If you are not using the MPW Version 3.0 (or later) development system, you can
  42220. achieve the same results as SetCurrentA5 and SetA5 by including the following
  42221. inline definitions:
  42222.  
  42223. FUNCTION SetCurrentA5 : LongInt;
  42224.   INLINE $2E8D, $2A78, $0904;
  42225.  
  42226. FUNCTION SetA5 (newA5 : LongInt) : LongInt;
  42227.   INLINE $2F4D, $0004, $2A5F;
  42228.  
  42229. If you are programming in assembly language, or are using a compiler that is not
  42230. able to handle multiple inline functions, you can use the following definitions:
  42231.  
  42232. SetCurrentA5
  42233.     move.l  A5,4(A7)      ;store old A5 as function result
  42234.     move.l  currentA5,A5  ;set A5 to low-memory global
  42235.     rts
  42236.  
  42237. SetA5
  42238.     move.l  (A7)+,A0  ;save return address
  42239.     move.l  A5,4(A7)  ;store old A5 as function result
  42240.     move.l  (A7)+,A5  ;set A5 to passed value
  42241.     jmp  (A0)
  42242.  
  42243. æKY SetA5
  42244. æFc OSUtils.h
  42245. æT Function
  42246. æD pascal long SetA5(long newA5)
  42247.     = {0x2F4D,0x0004,0x2A5F}; 
  42248. æDT long myVariable = SetA5((long) newA5);
  42249. æRT 136,208
  42250. æRI VI
  42251. æC 
  42252. Use the SetA5 function to set the A5 register to the application’s A5.
  42253.  
  42254. Calling SetA5 performs two tasks: it sets the A5 register to the address
  42255. specified as newA5, and returns the actual address that is in register A5 before
  42256. the function is called.
  42257.  
  42258. Note:  If you are using MPW Version 3.0 or later, you do not need to be
  42259. concerned with the information in this section.
  42260.   
  42261. If you are not using the MPW Version 3.0 (or later) development system, you can
  42262. achieve the same results as SetCurrentA5 and SetA5 by including the following
  42263. inline definitions:
  42264.  
  42265. FUNCTION SetCurrentA5 : LongInt;
  42266.   INLINE $2E8D, $2A78, $0904;
  42267.  
  42268. FUNCTION SetA5 (newA5 : LongInt) : LongInt;
  42269.   INLINE $2F4D, $0004, $2A5F;
  42270.  
  42271. If you are programming in assembly language, or are using a compiler that is not
  42272. able to handle multiple inline functions, you can use the following definitions:
  42273.  
  42274. SetCurrentA5
  42275.     move.l  A5,4(A7)      ;store old A5 as function result
  42276.     move.l  currentA5,A5  ;set A5 to low-memory global
  42277.     rts
  42278.  
  42279. SetA5
  42280.     move.l  (A7)+,A0  ;save return address
  42281.     move.l  A5,4(A7)  ;store old A5 as function result
  42282.     move.l  (A7)+,A5  ;set A5 to passed value
  42283.     jmp  (A0)
  42284.  
  42285. æKY Environs
  42286. æFc OSUtils.h
  42287. æT Function
  42288. æD pascal void Environs(short *rom,short *machine); 
  42289. æDT Environs((short *) rom,(short *) machine);
  42290. æRI II-385, IV-236
  42291. æC 
  42292. [Not in ROM]
  42293.  
  42294. In the rom parameter, Environs returns the current ROM version number (for a Macintosh
  42295. XL, the version number of the ROM image installed by MacWorks). To use the 128K ROM
  42296. information described in this volume, the version number should be greater than or
  42297. equal to 117 ($75). In the machine parameter, Environs returns an indication of which
  42298. machine is in use, as follows:
  42299.  
  42300. CONST  macXLMachine = 0;    {Macintosh XL}
  42301.        macMachine   = 1;    {Macintosh 128K, 512K, 512K upgraded, }
  42302.                             { 512K enhanced, or Macintosh Plus}
  42303.  
  42304. Note:  The machine parameter does not distinguish between the Macintosh 128K,
  42305.        512K, 512K upgraded, 512K enhanced, and Macintosh Plus.
  42306.  
  42307. Assembly-language note:  From assembly language, you can get this information
  42308.                          from the word that’s at an offset of 8 from the
  42309.                          beginning of ROM (which is stored in the global
  42310.                          variable ROMBase). The format of this word is $00xx
  42311.                          for the Macintosh 128K, 512K, 512K enhanced, or
  42312.                          Macintosh Plus, and $xxFF for the Macintosh XL, where
  42313.                          xx is the ROM version number. (The ROM version number
  42314.                          will always be between $01 and $FE.)
  42315.  
  42316. æKY Restart
  42317. æFc OSUtils.h
  42318. æT Function
  42319. æD pascal void Restart(void); 
  42320. æDT Restart()(void);
  42321. æMM
  42322. æRT 208
  42323. æRI II-385
  42324. æC 
  42325. [Not in ROM]
  42326.  
  42327. This procedure restarts the system.
  42328.  
  42329. Assembly-language note:  From assembly language, you can give the following
  42330.                          instructions to restart the system:
  42331.  
  42332.                            MOVE.L    ROMBase,A0
  42333.                            JMP       $0A(A0)
  42334.  
  42335. Note:  The procedures SetUpA5 and RestoreA5 were formerly documented in this
  42336.        chapter; however, two routines with more functionality are now available
  42337.        with the MPW 3.0 and later libraries.  The routines SetCurrentA5 and
  42338.        SetA5 are documented in Macintosh Technical Note #208.
  42339.  
  42340. •••Refer to Technical Note #208:•••
  42341.  
  42342. æKY RelString
  42343. æFc OSUtils.h
  42344. æT Function
  42345. æD pascal short RelString(const Str255 str1,const Str255 str2,Boolean caseSens,
  42346.     Boolean diacSens); 
  42347. æDT short myVariable = RelString((const Str255) str1,(const Str255) str2,(Boolean) caseSens,()
  42348.     Boolean diacSens);
  42349. æRI IV-234
  42350. æC 
  42351. Assembly-language note:  The trap macros for these utility routines have
  42352.                          optional arguments corresponding to the Pascal flags
  42353.                          passed to the routines. When present, such an argument
  42354.                          sets a certain bit of the routine trap word; this is
  42355.                          equivalent to setting the corresponding Pascal flag to
  42356.                          either TRUE or FALSE, depending on the flag. The trap
  42357.                          macros for these routines are listed with all the
  42358.                          possible permutations of arguments. Whichever
  42359.                          permutation you use, you must type it exactly as shown.
  42360.                          (The syntax shown applies to the Lisa Workshop
  42361.                          Assembler; programmers using another development
  42362.                          system should consult its documentation for the proper
  42363.                          syntax.)
  42364.  
  42365. RelString is similar to EqualString except that it indicates whether the first string
  42366. is less than, equal to, or greater than the second string by returning either –1, 0,
  42367. or 1 respectively.
  42368.  
  42369. Trap macro  _RelString
  42370.             _RelString ,MARKS       (sets bit 9, for diacSens=FALSE)
  42371.             _RelString ,CASE        (sets bit 10, for caseSens=TRUE)
  42372.             _RelString ,MARKS,CASE  (sets bits 9 and 10)
  42373. On entry    A0:  pointer to first character of first string
  42374.             A1:  pointer to first character of second string
  42375.             D0:  high-order word:  length of first string
  42376.                  low-order word:  length of second string
  42377. On exit     D0:  –1 if first string less than second, 0 if equal,
  42378.                   1 if first string greater than second (long word)
  42379.  
  42380. RelString follows the sort order described in the International Utilities Package
  42381. chapter except for the reordering of the following ligatures:
  42382.  
  42383.   Æ falls between Å and a
  42384.   æ falls between å and B
  42385.   Œ falls between Ø and o
  42386.   œ falls between ø and P
  42387.   ß falls between s and T
  42388.  
  42389. If diacSens is FALSE, diacritical marks are ignored; RelString strips diacriticals
  42390. according to the following table:
  42391.  
  42392.   A    <--    Ä, Å, À, Ã
  42393.   C    <--    Ç
  42394.   E    <--    É
  42395.   N    <--    Ñ
  42396.   O    <--    Ö, Õ, Ø
  42397.   U    <--    Ü
  42398.   a    <--    á, à, â, ä, ã, å, ª
  42399.   c    <--    ç
  42400.   e    <--    é, è, ê, ë
  42401.   i    <--    í, ì, î, ï
  42402.   n    <--    ñ
  42403.   o    <--    ó, ò, ô, ö, õ, ø, º
  42404.   u    <--    ú, ù, û, ü
  42405.   y    <--    ÿ
  42406.  
  42407. Note:  This stripping is identical to that performed by the UprString
  42408.        procedure when the diacSens parameter is FALSE.
  42409.  
  42410. If caseSens is FALSE, the comparison is not case-sensitive; RelString performs a
  42411. conversion from lower-case to upper-case characters according to the following table:
  42412.  
  42413.   A    <--    a
  42414.   ...  <--    ...
  42415.   Z    <--    z
  42416.   À    <--    à
  42417.   Ã    <--    ã
  42418.   Ä    <--    ä
  42419.   Å    <--    å
  42420.   Æ    <--    æ
  42421.   Ç    <--    ç
  42422.   É    <--    é
  42423.   Ñ    <--    ñ
  42424.   Ö    <--    ö
  42425.   Õ    <--    õ
  42426.   Ø    <--    ø
  42427.   Œ    <--    œ
  42428.   Ü    <--    ü
  42429.  
  42430. Note:  This conversion is identical to that performed by the UprString
  42431.        procedure.
  42432.  
  42433. æKY relstring
  42434. æFc OSUtils.h
  42435. æT Function
  42436. æD short relstring(char *str1,char *str2,Boolean caseSens,Boolean diacSens); 
  42437. æDT short myVariable = relstring((char *) str1,(char *) str2,(Boolean) caseSens,(Boolean) diacSens);
  42438. æC 
  42439.  
  42440. æKY HandToHand
  42441. æFc OSUtils.h
  42442. æT Function
  42443. æD pascal OSErr HandToHand(Handle *theHndl); 
  42444. æDT OSErr myVariable = HandToHand((Handle *) theHndl);
  42445. æMM
  42446. æRI II-374
  42447. æC 
  42448. Trap macro  _HandToHand
  42449. On entry    A0:  theHndl (handle)
  42450. On exit     A0:  theHndl (handle)
  42451.             D0:  result code (word)
  42452.  
  42453. HandToHand copies the information to which theHndl is a handle and returns a new
  42454. handle to the copy in theHndl. Since HandToHand replaces the input parameter with a
  42455. new handle, you should retain the original value of the input parameter somewhere
  42456. else, or you won’t be able to access it. For example:
  42457.  
  42458.   VAR    x,y:  Handle;
  42459.          err:  OSErr;
  42460.   y := x;
  42461.   err := HandToHand(y)
  42462.  
  42463. The original handle remains in x while y becomes a different handle to an identical
  42464. copy of the data.
  42465.  
  42466. Result codes    noErr           No error
  42467.                 memFullErr      Not enough room in heap zone
  42468.                 nilHandleErr    NIL master pointer
  42469.                 memWZErr        Attempt to operate on a free block
  42470.  
  42471. æKY PtrToXHand
  42472. æFc OSUtils.h
  42473. æT Function
  42474. æD pascal OSErr PtrToXHand(Ptr srcPtr,Handle dstHndl,long size); 
  42475. æDT OSErr myVariable = PtrToXHand((Ptr) srcPtr,(Handle) dstHndl,(long) size);
  42476. æMM
  42477. æRI II-375
  42478. æC 
  42479. Trap macro  _PtrToXHand
  42480. On entry    A0:  srcPtr (pointer)
  42481.             A1:  dstHndl (handle)
  42482.             D0:  size (long word)
  42483. On exit     A0:  dstHndl (handle)
  42484.             D0:  result code (word)
  42485.  
  42486. PtrToXHand takes the existing handle specified by dstHndl and makes it a handle to a
  42487. copy of the number of bytes specified by the size parameter, beginning at the location
  42488. specified by srcPtr.
  42489.  
  42490. Result codes    noErr           No error
  42491.                 memFullErr      Not enough room in heap zone
  42492.                 nilHandleErr    NIL master pointer
  42493.                 memWZErr        Attempt to operate on a free block
  42494.  
  42495. æKY PtrToHand
  42496. æFc OSUtils.h
  42497. æT Function
  42498. æD pascal OSErr PtrToHand(Ptr srcPtr,Handle *dstHndl,long size); 
  42499. æDT OSErr myVariable = PtrToHand((Ptr) srcPtr,(Handle *) dstHndl,(long) size);
  42500. æMM
  42501. æRI II-375
  42502. æC 
  42503. Trap macro  _PtrToHand
  42504. On entry    A0:  srcPtr (pointer)
  42505.             D0:  size (long word)
  42506. On exit     A0:  dstHndl (handle)
  42507.             D0:  result code (word)
  42508.  
  42509. PtrToHand returns in dstHndl a newly created handle to a copy of the number of bytes
  42510. specified by the size parameter, beginning at the location specified by srcPtr.
  42511.  
  42512. Result codes    noErr         No error
  42513.                 memFullErr    Not enough room in heap zone
  42514.  
  42515. æKY HandAndHand
  42516. æFc OSUtils.h
  42517. æT Function
  42518. æD pascal OSErr HandAndHand(Handle hand1,Handle hand2); 
  42519. æDT OSErr myVariable = HandAndHand((Handle) hand1,(Handle) hand2);
  42520. æMM
  42521. æRI II-375
  42522. æC 
  42523. Trap macro  _HandAndHand
  42524. On entry    A0:  aHndl (handle)
  42525.             A1:  bHndl (handle)
  42526. On exit     A0:  bHndl (handle)
  42527.             D0:  result code (word)
  42528.  
  42529. HandAndHand concatenates the information to which aHndl is a handle onto the end of
  42530. the information to which bHndl is a handle.
  42531.  
  42532. Warning:  HandAndHand dereferences aHndl, so be sure to call the Memory
  42533.           Manager procedure HLock to lock the block before calling HandAndHand.
  42534.  
  42535. Result codes    noErr           No error
  42536.                 memFullErr      Not enough room in heap zone
  42537.                 nilHandleErr    NIL master pointer
  42538.                 memWZErr        Attempt to operate on a free block
  42539.  
  42540. æKY PtrAndHand
  42541. æFc OSUtils.h
  42542. æT Function
  42543. æD pascal OSErr PtrAndHand(Ptr ptr1,Handle hand2,long size); 
  42544. æDT OSErr myVariable = PtrAndHand((Ptr) ptr1,(Handle) hand2,(long) size);
  42545. æMM
  42546. æRI II-376
  42547. æC 
  42548. Trap macro  _PtrAndHand
  42549. On entry    A0:  pntr (pointer)
  42550.             A1:  hndl (handle)
  42551.             D0:  size (long word)
  42552. On exit     A0:  hndl (handle)
  42553.             D0:  result code (word)
  42554.  
  42555. PtrAndHand takes the number of bytes specified by the size parameter, beginning at
  42556. the location specified by pntr, and concatenates them onto the end of the information
  42557. to which hndl is a handle.
  42558.  
  42559. Result codes    noErr           No error
  42560.                 memFullErr      Not enough room in heap zone
  42561.                 nilHandleErr    NIL master pointer
  42562.                 memWZErr        Attempt to operate on a free block
  42563.  
  42564. æKY InitUtil
  42565. æFc OSUtils.h
  42566. æT Function
  42567. æTN A03F
  42568. æD pascal OSErr InitUtil(void)
  42569.     = {0xA03F,0x3E80}; 
  42570. æDT OSErr myVariable = InitUtil()(void);
  42571. æRI II-380
  42572. æC 
  42573. Trap macro  _InitUtil
  42574. On exit     D0:  result code (word)
  42575.  
  42576. •••Refer to Figure 4.•••
  42577.  
  42578. Figure 4–Parameter RAM Routines
  42579.  
  42580. InitUtil copies the contents of parameter RAM into 20 bytes of low memory and copies
  42581. the date and time from the clock chip into its own low-memory location. This routine
  42582. is called at system startup; you’ll probably never need to call it yourself.
  42583.  
  42584. Assembly-language note:  InitUtil copies parameter RAM into 20 bytes starting
  42585.                          at the address SysParam and copies the date and time
  42586.                          into the global variable Time.
  42587.  
  42588. If the validity status in parameter RAM is not $A8 when InitUtil is called, an error
  42589. is returned as the result code, and the default values (given in the
  42590. “Parameter RAM” section) are read into the low-memory copy of parameter RAM; these
  42591. values are then written to the clock chip itself.
  42592.  
  42593. Result codes    noErr        No error
  42594.                 prInitErr    Validity status not $A8
  42595.  
  42596. æKY SwapInstructionCache
  42597. æFc OSUtils.h
  42598. æT Function
  42599. æD pascal Boolean SwapInstructionCache(Boolean cacheEnable); 
  42600. æDT Boolean myVariable = SwapInstructionCache((Boolean) cacheEnable);
  42601. æC 
  42602.  
  42603. æKY FlushInstructionCache
  42604. æFc OSUtils.h
  42605. æT Function
  42606. æD pascal void FlushInstructionCache(void); 
  42607. æDT FlushInstructionCache()(void);
  42608. æC 
  42609.  
  42610. æKY SwapDataCache
  42611. æFc OSUtils.h
  42612. æT Function
  42613. æD pascal Boolean SwapDataCache(Boolean cacheEnable); 
  42614. æDT Boolean myVariable = SwapDataCache((Boolean) cacheEnable);
  42615. æC 
  42616.  
  42617. æKY FlushDataCache
  42618. æFc OSUtils.h
  42619. æT Function
  42620. æD pascal void FlushDataCache(void); 
  42621. æDT FlushDataCache()(void);
  42622. æC 
  42623.  
  42624.  
  42625. æKY OutlineCalls.h
  42626. æKL ApplyFontMapping
  42627. CountFondFaces
  42628. CountFontFamilies
  42629. CountFontGlyphs
  42630. CountFontMappings
  42631. CountFontStrings
  42632. CountFontTables
  42633. DetachFontFace
  42634. DisposeFontFace
  42635. DisposeFontFamily
  42636. FlushFonts
  42637. FOND2FontFamily
  42638. GetAllGlyphPSNames
  42639. GetFontFace
  42640. GetFontFaceName
  42641. GetFontFamily
  42642. GetFontFamilyName
  42643. GetFontMappingInfo
  42644. GetFontString
  42645. GetFontStringInfo
  42646. GetFontTable
  42647. GetFontTableInfo
  42648. GetFontTablePart
  42649. GetGlyphPSName
  42650. GetOutlinePreferred
  42651. GetPreserveGlyph
  42652. GetPSFontName
  42653. IsOutline
  42654. NewFontFace
  42655. NewFontFamily
  42656. OutlineMetrics
  42657. SetOutlinePreferred
  42658. SetPreserveGlyph
  42659. sfnt2FontFace
  42660.  
  42661. APPLY_FONT_MAPPING
  42662. BITFONT_ERR
  42663. COUNT_FOND_FACES
  42664. COUNT_FONT_FAMILIES
  42665. COUNT_FONT_GLYPHS
  42666. COUNT_FONT_MAPPINGS
  42667. COUNT_FONT_STRINGS
  42668. COUNT_FONT_TABLES
  42669. DETACH_FONT_FACE
  42670. DISPOSE_FONT_FACE
  42671. DISPOSE_FONT_FAMILY
  42672. FLUSH_FONTS
  42673. FOND_2_FONT_FAMILY
  42674. fontError
  42675. fontFace
  42676. fontFamily
  42677. fontStringInfo
  42678. GET_ALL_GLYPH_PS_NAMES
  42679. GET_FONT_FACE
  42680. GET_FONT_FACE_NAME
  42681. GET_FONT_FAMILY
  42682. GET_FONT_FAMILY_NAME
  42683. GET_FONT_MAPPING_INFO
  42684. GET_FONT_STRING
  42685. GET_FONT_STRING_INFO
  42686. GET_FONT_TABLE
  42687. GET_FONT_TABLE_INFO
  42688. GET_FONT_TABLE_PART
  42689. GET_GLYPH_PS_NAME
  42690. GET_OUTLINEPREFERRED
  42691. GET_PRESERVE_GLYPHS
  42692. GET_PS_FONT_NAME
  42693. IS_OUTLINE
  42694. kBadFamilyIndex
  42695. kBadFont
  42696. kBadFontFaceIndex
  42697. kBadFontFaceName
  42698. kBadMappingIndex
  42699. kBadTableFormat
  42700. kCannotLoadFamily
  42701. kCannotLoadFont
  42702. kFontMemoryError
  42703. kFontStringNotFound
  42704. kFontTableNotFound
  42705. kNoFontError
  42706. kNoStyleSizeMatch
  42707. kUnknownMappingFormat
  42708. NEW_FONT_FACE
  42709. NEW_FONT_FAMILY
  42710. OUTLINE_METRICS
  42711. SET_OUTLINEPREFERRED
  42712. SET_PRESERVE_GLYPHS
  42713. SFNT_2_FONT_FACE
  42714. tableTag
  42715.  
  42716. æKY BITFONT_ERR
  42717. æFc OutlineCalls.h
  42718. æT #define
  42719. æD 
  42720. /* ERRORS */
  42721.  
  42722. #define BITFONT_ERR 0x8099 /* Outline metrics was called with a bitmap font */
  42723. æC 
  42724.  
  42725. æKY IS_OUTLINE
  42726. æFc OutlineCalls.h
  42727. æT #define
  42728. æD 
  42729. /* Selectors */
  42730.  
  42731. #define IS_OUTLINE 0x0000
  42732. æC 
  42733.  
  42734. æKY SET_OUTLINEPREFERRED
  42735. æFc OutlineCalls.h
  42736. æT #define
  42737. æD #define SET_OUTLINEPREFERRED 0x0001
  42738. æC 
  42739.  
  42740. æKY OUTLINE_METRICS
  42741. æFc OutlineCalls.h
  42742. æT #define
  42743. æD #define OUTLINE_METRICS 0x0008
  42744. æC 
  42745.  
  42746. æKY GET_OUTLINEPREFERRED
  42747. æFc OutlineCalls.h
  42748. æT #define
  42749. æD #define GET_OUTLINEPREFERRED 0x0009
  42750. æC 
  42751.  
  42752. æKY SET_PRESERVE_GLYPHS
  42753. æFc OutlineCalls.h
  42754. æT #define
  42755. æD #define SET_PRESERVE_GLYPHS 0x000A
  42756. æC 
  42757.  
  42758. æKY GET_PRESERVE_GLYPHS
  42759. æFc OutlineCalls.h
  42760. æT #define
  42761. æD #define GET_PRESERVE_GLYPHS 0x000B
  42762. æC 
  42763.  
  42764. æKY FLUSH_FONTS
  42765. æFc OutlineCalls.h
  42766. æT #define
  42767. æD #define FLUSH_FONTS 0x000C
  42768. æC 
  42769.  
  42770. æKY GET_PS_FONT_NAME
  42771. æFc OutlineCalls.h
  42772. æT #define
  42773. æD #define GET_PS_FONT_NAME 0x000F
  42774. æC 
  42775.  
  42776. æKY COUNT_FONT_FAMILIES
  42777. æFc OutlineCalls.h
  42778. æT #define
  42779. æD #define COUNT_FONT_FAMILIES 0x0010
  42780. æC 
  42781.  
  42782. æKY GET_FONT_FAMILY_NAME
  42783. æFc OutlineCalls.h
  42784. æT #define
  42785. æD #define GET_FONT_FAMILY_NAME 0x0011
  42786. æC 
  42787.  
  42788. æKY NEW_FONT_FAMILY
  42789. æFc OutlineCalls.h
  42790. æT #define
  42791. æD #define NEW_FONT_FAMILY 0x0012
  42792. æC 
  42793.  
  42794. æKY FOND_2_FONT_FAMILY
  42795. æFc OutlineCalls.h
  42796. æT #define
  42797. æD #define FOND_2_FONT_FAMILY 0x0013
  42798. æC 
  42799.  
  42800. æKY DISPOSE_FONT_FAMILY
  42801. æFc OutlineCalls.h
  42802. æT #define
  42803. æD #define DISPOSE_FONT_FAMILY 0x0014
  42804. æC 
  42805.  
  42806. æKY GET_FONT_FAMILY
  42807. æFc OutlineCalls.h
  42808. æT #define
  42809. æD #define GET_FONT_FAMILY 0x0015
  42810. æC 
  42811.  
  42812. æKY COUNT_FOND_FACES
  42813. æFc OutlineCalls.h
  42814. æT #define
  42815. æD #define COUNT_FOND_FACES 0x0016
  42816. æC 
  42817.  
  42818. æKY GET_FONT_FACE_NAME
  42819. æFc OutlineCalls.h
  42820. æT #define
  42821. æD #define GET_FONT_FACE_NAME 0x0017
  42822. æC 
  42823.  
  42824. æKY NEW_FONT_FACE
  42825. æFc OutlineCalls.h
  42826. æT #define
  42827. æD #define NEW_FONT_FACE 0x0018
  42828. æC 
  42829.  
  42830. æKY SFNT_2_FONT_FACE
  42831. æFc OutlineCalls.h
  42832. æT #define
  42833. æD #define SFNT_2_FONT_FACE 0x0019
  42834. æC 
  42835.  
  42836. æKY DISPOSE_FONT_FACE
  42837. æFc OutlineCalls.h
  42838. æT #define
  42839. æD #define DISPOSE_FONT_FACE 0x001A
  42840. æC 
  42841.  
  42842. æKY GET_FONT_FACE
  42843. æFc OutlineCalls.h
  42844. æT #define
  42845. æD #define GET_FONT_FACE 0x001B
  42846. æC 
  42847.  
  42848. æKY DETACH_FONT_FACE
  42849. æFc OutlineCalls.h
  42850. æT #define
  42851. æD #define DETACH_FONT_FACE 0x001C
  42852. æC 
  42853.  
  42854. æKY COUNT_FONT_TABLES
  42855. æFc OutlineCalls.h
  42856. æT #define
  42857. æD #define COUNT_FONT_TABLES 0x001D
  42858. æC 
  42859.  
  42860. æKY GET_FONT_TABLE_INFO
  42861. æFc OutlineCalls.h
  42862. æT #define
  42863. æD #define GET_FONT_TABLE_INFO 0x001E
  42864. æC 
  42865.  
  42866. æKY GET_FONT_TABLE
  42867. æFc OutlineCalls.h
  42868. æT #define
  42869. æD #define GET_FONT_TABLE 0x001F
  42870. æC 
  42871.  
  42872. æKY GET_FONT_TABLE_PART
  42873. æFc OutlineCalls.h
  42874. æT #define
  42875. æD #define GET_FONT_TABLE_PART 0x0020
  42876. æC 
  42877.  
  42878. æKY COUNT_FONT_STRINGS
  42879. æFc OutlineCalls.h
  42880. æT #define
  42881. æD #define COUNT_FONT_STRINGS 0x0021
  42882. æC 
  42883.  
  42884. æKY GET_FONT_STRING_INFO
  42885. æFc OutlineCalls.h
  42886. æT #define
  42887. æD #define GET_FONT_STRING_INFO 0x0022
  42888. æC 
  42889.  
  42890. æKY GET_FONT_STRING
  42891. æFc OutlineCalls.h
  42892. æT #define
  42893. æD #define GET_FONT_STRING 0x0023
  42894. æC 
  42895.  
  42896. æKY COUNT_FONT_MAPPINGS
  42897. æFc OutlineCalls.h
  42898. æT #define
  42899. æD #define COUNT_FONT_MAPPINGS 0x0024
  42900. æC 
  42901.  
  42902. æKY GET_FONT_MAPPING_INFO
  42903. æFc OutlineCalls.h
  42904. æT #define
  42905. æD #define GET_FONT_MAPPING_INFO 0x0025
  42906. æC 
  42907.  
  42908. æKY APPLY_FONT_MAPPING
  42909. æFc OutlineCalls.h
  42910. æT #define
  42911. æD #define APPLY_FONT_MAPPING 0x0026
  42912. æC 
  42913.  
  42914. æKY COUNT_FONT_GLYPHS
  42915. æFc OutlineCalls.h
  42916. æT #define
  42917. æD #define COUNT_FONT_GLYPHS 0x0027
  42918. æC 
  42919.  
  42920. æKY GET_GLYPH_PS_NAME
  42921. æFc OutlineCalls.h
  42922. æT #define
  42923. æD #define GET_GLYPH_PS_NAME 0x0028
  42924. æC 
  42925.  
  42926. æKY GET_ALL_GLYPH_PS_NAMES
  42927. æFc OutlineCalls.h
  42928. æT #define
  42929. æD #define GET_ALL_GLYPH_PS_NAMES 0x0029
  42930. æC 
  42931.  
  42932. æKY fontFamily
  42933. æFc OutlineCalls.h
  42934. æT typedef
  42935. æD typedef struct { void* aFontFamily; } *fontFamily;
  42936. æC 
  42937.  
  42938. æKY fontFace
  42939. æFc OutlineCalls.h
  42940. æT typedef
  42941. æD typedef struct { void* aFontFace; } *fontFace;
  42942. æC 
  42943.  
  42944. æKY tableTag
  42945. æFc OutlineCalls.h
  42946. æT typedef
  42947. æD 
  42948. typedef long tableTag;
  42949. æC 
  42950.  
  42951. æKY fontError
  42952. kNoFontError
  42953. kBadFont
  42954. kFontTableNotFound
  42955. kFontStringNotFound
  42956. kUnknownMappingFormat
  42957. kBadMappingIndex
  42958. kBadFontFaceIndex
  42959. kBadFontFaceName
  42960. kCannotLoadFamily
  42961. kCannotLoadFont
  42962. kNoStyleSizeMatch
  42963. kBadFamilyIndex
  42964. kBadTableFormat
  42965. kFontMemoryError
  42966.  
  42967. æFc OutlineCalls.h
  42968. æT enum
  42969. æD enum {kNoFontError,kBadFont,kFontTableNotFound,kFontStringNotFound,kUnknownMappingFormat,
  42970.     kBadMappingIndex,kBadFontFaceIndex,kBadFontFaceName,kCannotLoadFamily,
  42971.     kCannotLoadFont,kNoStyleSizeMatch,kBadFamilyIndex,kBadTableFormat,kFontMemoryError};
  42972. typedef unsigned char fontError;
  42973. æC 
  42974.  
  42975. æKY fontStringInfo
  42976. æFc OutlineCalls.h
  42977. æT struct
  42978. æD struct fontStringInfo {
  42979.     short platfrom;
  42980.     short script;
  42981.     short language;
  42982.     short meaning;
  42983. };
  42984.  
  42985. typedef struct fontStringInfo fontStringInfo;
  42986. æC 
  42987.  
  42988. æKY IsOutline
  42989. æFc OutlineCalls.h
  42990. æT Function
  42991. æTN A854
  42992. æD 
  42993. pascal Boolean IsOutline(Point numer,Point denom)
  42994.     = {0x7000,0xA854}; 
  42995. æDT Boolean myVariable = IsOutline((Point) numer,(Point) denom);
  42996. æRI VI
  42997. æC  
  42998. The IsOutline function returns TRUE if the current grafPort has loaded an
  42999. outline font and FALSE if it has loaded a bitmap font. It does not affect the
  43000. state of the outlinePreferred variable. The IsOutline function uses the numer
  43001. and denom parameters to determine which size of the font the Font Manager should
  43002. look for.
  43003.  
  43004. æKY SetOutlinePreferred
  43005. æFc OutlineCalls.h
  43006. æT Function
  43007. æTN A854
  43008. æD 
  43009. pascal void SetOutlinePreferred(Boolean outlinePreferred)
  43010.     = {0x7001,0xA854}; 
  43011. æDT 
  43012. SetOutlinePreferred((Boolean) outlinePreferred);
  43013. æRI VI
  43014. æC  
  43015. You can use the SetOutlinePreferred procedure to choose whether bitmap fonts or
  43016. outline fonts should be used, if both happen to be available. The
  43017. GetOutlinePreferred function returns the current setting of the OutlinePreferred
  43018. global variable. You can use the IsOutline function to determine whether a
  43019. grafPort uses an outline font or a bitmap font.
  43020.  
  43021. The SetOutlinePreferred procedure lets you specify that the Font Manager is to
  43022. use an outline font rather than the equivalent bitmap font when both an 'sfnt'
  43023. resource and a 'FONT' or 'NFNT' resource for that font are present in the
  43024. system. The value of the OutlinePreferred global variable affects only one
  43025. application and all of its open grafPort records.
  43026.  
  43027. A GrafPort record contains a field that specifies the text font. If both an
  43028. outline font and a bitmap font exist for the font requested, the setting of the
  43029. OutlinePreferred global variable decides which should be used. The bitmap font
  43030. must be precisely the name, style, and point size requested. 
  43031.  
  43032. If you set the doOutline parameter to TRUE, you are setting the global variable
  43033. OutlinePreferred to TRUE and the Font Manager always chooses the outline font
  43034. for all subsequent text drawing, even if an appropriate bitmap font is
  43035. available. If you set it to FALSE, the Font Manager chooses the bitmap font when
  43036. drawing. To ensure compatibility with existing applications, the Font Manager
  43037. chooses bitmap fonts by default.
  43038.  
  43039. If only an outline font or only a bitmap font is available to an application,
  43040. the Font Manager uses the available font without regard to the value of the
  43041. OutlinePreferred global variable. 
  43042.  
  43043. æKY GetOutlinePreferred
  43044. æFc OutlineCalls.h
  43045. æT Function
  43046. æTN A854
  43047. æD 
  43048. pascal Boolean GetOutlinePreferred(void)
  43049.     = {0x7009,0xA854}; 
  43050. æDT Boolean myVariable = GetOutlinePreferred()(void);
  43051. æRI VI
  43052. æC  
  43053. The GetOutlinePreferred function returns the current state of the
  43054. outlinePreferred parameter, which determines whether an outline font or a bitmap
  43055. font should be used by the current grafPort.
  43056.  
  43057.  
  43058.  
  43059. æKY OutlineMetrics
  43060. æFc OutlineCalls.h
  43061. æT Function
  43062. æTN A854
  43063. æD 
  43064. pascal OSErr OutlineMetrics(short count,Ptr textPtr,Point numer,Point denom,
  43065.     short *yMax,short *yMin,Fixed *awArray,Fixed *IsbArray,Rect *boundsArray)
  43066.     = {0x7008,0xA854}; 
  43067. æDT OSErr myVariable = OutlineMetrics((short) count,(Ptr) textPtr,(Point) numer,(Point) denom,(
  43068.     short) * yMax,(short *) yMin,(Fixed *) awArray,(Fixed *) IsbArray,(Rect *) boundsArray);
  43069. æRI VI
  43070. æC  
  43071. The GetPreserveGlyph function returns the current setting of the preserveGlyph
  43072. parameter. You can use the FlushFonts procedure to erase all of the Font
  43073. Manager’s memory caches.
  43074.  
  43075. FUNCTION OutLineMetrics (byteCount: Integer; textPtr: Ptr; numer,denom:  
  43076.                          Point; VAR yMax: Integer; VAR yMin: Integer;
  43077.                          awArray: TPFixed; lsbArray: TPFixed;
  43078.                          boundsArray: TRectPtr) : OSErr;
  43079.  
  43080. The OutlineMetrics function returns the measurements of the glyphs in the text
  43081. pointed to by the textPtr parameter for the font in the current grafPort. 
  43082.  
  43083. Parameter    Descriptions
  43084.  
  43085. byteCount    The number of bytes on which you want the OutlineMetrics function
  43086.              to operate. 
  43087.  
  43088. textPtr      The pointer to the block of text you are providing to the 
  43089.              OutlineMetrics function. 
  43090.  
  43091. numer        The numerator of the scaling factor. Numer is of type Point, which 
  43092.              contains two integers—the first for vertical scaling, the second 
  43093.              for horizontal scaling.
  43094.  
  43095. denom        The denominator of the scaling factor. Numer is of type Point, 
  43096.              which contains two integers—the first for vertical scaling, the 
  43097.              second for horizontal scaling.
  43098.  
  43099. yMax         The maximum y-value, or ascent line, for the glyphs.
  43100.  
  43101. yMin         The minimum y-value, or descent line, for the glyphs.
  43102.  
  43103. awArray      A pointer to the array of advance-width measurements for the glyphs
  43104.  
  43105.              being considered. The number of entries in the array is given by 
  43106.              the glyphCount parameter. 
  43107.  
  43108.              You must allocate the memory needed for the array and pass a      
  43109.  
  43110.              pointer to the array in the awArray parameter. The awArray 
  43111.              parameter is of type TPFixed, which is a pointer to the Fixed data 
  43112.              type, which is 4 bytes in length.  You need to multiply glyphCount 
  43113.              by 4 to calculate the memory you need in bytes.
  43114.  
  43115.              If the FractEnable variable has been set to TRUE using the 
  43116.              SetFractEnable procedure, the values in awArray are real numbers. 
  43117.              The SetFractEnable procedure is discussed in the Font Manager 
  43118.              chapter of Volume IV.
  43119.  
  43120. lsbArray     A pointer to the array of left-side bearing measurements for the 
  43121.              glyphs being considered. The number of entries in the array is 
  43122.              given by the glyphCount parameter.
  43123.  
  43124.              You must allocate the memory needed for the array and pass a 
  43125.              pointer to the array in the lsbArray parameter. The lsbArray 
  43126.              parameter is of type TPFixed, which is a pointer to the Fixed data 
  43127.              type, which is 4 bytes in length.  You need to multiply glyphCount 
  43128.              by 4 to calculate the memory you need in bytes.
  43129.  
  43130. boundsArray  A pointer to the array of bounding measurements for the glyphs 
  43131.              being considered. The number of entries in the array is given by 
  43132.              the glyphCount parameter.
  43133.  
  43134.              These bounding boxes are the smallest rectangles that fit around 
  43135.              the pixels of the glyph. You must allocate the memory needed for 
  43136.              the array and pass a pointer to the array in the boundsArray 
  43137.              parameter. The boundsArray parameter is of type TRectPtr, which is 
  43138.              pointer to the Rect data type, which is 8 bytes in length.  You 
  43139.              need to multiply glyphCount by 8 to calculate the memory you need 
  43140.              in bytes.
  43141.  
  43142. Pass a NIL value for each parameter you don’t want returned. If you do not
  43143. specify NIL for the awArray, lsbArray, and boundsArray parameters, you must
  43144. allocate enough memory to contain the number of cells needed for the array.
  43145.  
  43146. If you set the Boolean variable preserveGlyph to TRUE using the SetPreserveGlyph
  43147. procedure, you should use the OutlineMetrics function to determine the line
  43148. height for the glyphs in question and calculate whether the leading for the line
  43149. or paragraph needs to be changed to avoid collisions between lines.
  43150.  
  43151. æKY SetPreserveGlyph
  43152. æFc OutlineCalls.h
  43153. æT Function
  43154. æTN A854
  43155. æD 
  43156. pascal void SetPreserveGlyph(Boolean preserveGlyphs)
  43157.     = {0x700A,0xA854}; 
  43158. æDT 
  43159. SetPreserveGlyph((Boolean) preserveGlyphs);
  43160. æRI VI
  43161. æC  
  43162. The SetPreserveGlyph procedure lets you choose whether the Font Manager should
  43163. preserve the original form of a glyph or scale it to fit between the ascent and
  43164. descent lines.  
  43165.  
  43166. If a glyph’s ascender goes above the ascent line or its descender goes below the
  43167. descent line of the font, the Font Manager scales the glyph in the y-direction
  43168. to fit it within the ascent and descent lines exactly. You can use the
  43169. SetPreserveGlyph procedure to preserve the original form of the glyph and avoid
  43170. crushing it to fit the line. The value of the PreserveGlyph global variable
  43171. affects only one application at a time.
  43172.  
  43173. If you set the doPreserve parameter to TRUE, you are setting the global variable
  43174. PreserveGlyph to TRUE and the application preserves the original forms of all
  43175. the glyphs in the font, even if they go above the ascent line or below the
  43176. descent line. Note that this could result in the edges of glyphs touching or
  43177. possibly overwriting the lines above or below them. It is up to your application
  43178. to redraw the line using the appropriate line height for the ascent or descent
  43179. measurements of the glyphs in that line.You can use the OutlineMetrics function
  43180. to determine what the ascent or descent of the glyphs on a line is. 
  43181.  
  43182. If you set it to FALSE, the Font Manager scales the glyphs in the current
  43183. grafPort to fit between the ascent and descent lines. To ensure compatibility
  43184. with existing applications, glyphs are scaled to fit within the given
  43185. measurements and possibly may look squashed.
  43186.  
  43187. æKY GetPreserveGlyph
  43188. æFc OutlineCalls.h
  43189. æT Function
  43190. æTN A854
  43191. æD 
  43192. pascal Boolean GetPreserveGlyph(void)
  43193.     = {0x700B,0xA854}; 
  43194. æDT Boolean myVariable = GetPreserveGlyph()(void);
  43195. æRI VI
  43196. æC  
  43197. The GetPreserveGlyph function returns the current state of the Boolean variable
  43198. preserveGlyph, which determines whether the form of a glyph should be preserved
  43199. with its original measurements or scaled to fit the ascent and descent
  43200. measurements of the line.
  43201.  
  43202. æKY FlushFonts
  43203. æFc OutlineCalls.h
  43204. æT Function
  43205. æTN A854
  43206. æD 
  43207. pascal OSErr FlushFonts(void)
  43208.     = {0x700C,0xA854}; 
  43209. æDT OSErr myVariable = FlushFonts()(void);
  43210. æRI VI
  43211. æC  
  43212. The FlushFonts function purges the Font Manager’s memory caches. This function
  43213. should be used mainly by font editors or other applications that directly
  43214. manipulate font data. The Font Manager caches may include the width tables, the
  43215. bitmaps created from the outlines of the 'sfnt' resource, the outlines, and a
  43216. small cache of 'FOND' resources that have been read into memory.
  43217.  
  43218.   Note: This function flushes all caches from memory. If you ask for bitmaps of
  43219.  
  43220.   the current font after calling FlushFonts, these bitmaps must be rendered 
  43221.   again.
  43222.  
  43223.  
  43224. æKY GetPSFontName
  43225. æFc OutlineCalls.h
  43226. æT Function
  43227. æTN A854
  43228. æD 
  43229. pascal OSErr GetPSFontName(short txFont,short txFace,const Str255 psName)
  43230.     = {0x700F,0xA854}; 
  43231. æDT OSErr myVariable = GetPSFontName((short) txFont,(short) txFace,(const Str255) psName);
  43232. æRI 
  43233. æC  
  43234.  
  43235. æKY CountFontFamilies
  43236. æFc OutlineCalls.h
  43237. æT Function
  43238. æTN A854
  43239. æD 
  43240. pascal long CountFontFamilies(void)
  43241.     = {0x7010,0xA854}; 
  43242. æDT long myVariable = CountFontFamilies()(void);
  43243. æRI 
  43244. æC  
  43245.  
  43246. æKY GetFontFamilyName
  43247. æFc OutlineCalls.h
  43248. æT Function
  43249. æTN A854
  43250. æD 
  43251. pascal void GetFontFamilyName(long index,const Str255 familyName)
  43252.     = {0x7011,0xA854}; 
  43253. æDT 
  43254. GetFontFamilyName((long) index,(const Str255) familyName);
  43255. æRI 
  43256. æC  
  43257.  
  43258. æKY NewFontFamily
  43259. æFc OutlineCalls.h
  43260. æT Function
  43261. æTN A854
  43262. æD 
  43263. pascal fontFamily NewFontFamily(long index,const Str255 familyName)
  43264.     = {0x7012,0xA854}; 
  43265. æDT fontFamily myVariable = NewFontFamily((long) index,(const Str255) familyName);
  43266. æRI 
  43267. æC
  43268.  
  43269. æKY FOND2FontFamily
  43270. æFc OutlineCalls.h
  43271. æT Function
  43272. æTN A854
  43273. æD 
  43274. pascal fontFamily FOND2FontFamily(Handle fond)
  43275.     = {0x7013,0xA854}; 
  43276. æDT fontFamily myVariable = FOND2FontFamily((Handle) fond);
  43277. æRI 
  43278. æC  
  43279.  
  43280. æKY DisposeFontFamily
  43281. æFc OutlineCalls.h
  43282. æT Function
  43283. æTN A854
  43284. æD 
  43285. pascal void DisposeFontFamily(fontFamily theFontFamily)
  43286.     = {0x7014,0xA854}; 
  43287. æDT 
  43288. DisposeFontFamily((fontFamily) theFontFamily);
  43289. æRI
  43290. æC  
  43291.  
  43292. æKY GetFontFamily
  43293. æFc OutlineCalls.h
  43294. æT Function
  43295. æTN A854
  43296. æD 
  43297. pascal void GetFontFamily(fontFamily theFontFamily,const Str255 familyName)
  43298.     = {0x7015,0xA854}; 
  43299. æDT 
  43300. GetFontFamily((fontFamily) theFontFamily,(const Str255) familyName);
  43301. æRI 
  43302. æC  
  43303.  
  43304. æKY CountFondFaces
  43305. æFc OutlineCalls.h
  43306. æT Function
  43307. æTN A854
  43308. æD 
  43309. pascal long CountFondFaces(fontFamily theFontFamily)
  43310.     = {0x7016,0xA854}; 
  43311. æDT long myVariable = CountFondFaces((fontFamily) theFontFamily);
  43312. æRI 
  43313. æC  
  43314.  
  43315. æKY GetFontFaceName
  43316. æFc OutlineCalls.h
  43317. æT Function
  43318. æTN A854
  43319. æD 
  43320. pascal void GetFontFaceName(fontFamily theFontFamily,long index,const Str255 fontName)
  43321.     = {0x7017,0xA854}; 
  43322. æDT 
  43323. GetFontFaceName((fontFamily) theFontFamily,(long) index,(const Str255) fontName);
  43324. æRI 
  43325. æC  
  43326.  
  43327. æKY NewFontFace
  43328. æFc OutlineCalls.h
  43329. æT Function
  43330. æTN A854
  43331. æD 
  43332. pascal fontFace NewFontFace(fontFamily theFontFamily,long index,const Str255 fontName)
  43333.     = {0x7018,0xA854}; 
  43334. æDT fontFace myVariable = NewFontFace((fontFamily) theFontFamily,(long) index,(const Str255) fontName);
  43335. æRI 
  43336. æC  
  43337.  
  43338. æKY sfnt2FontFace
  43339. æFc OutlineCalls.h
  43340. æT Function
  43341. æTN A854
  43342. æD 
  43343. pascal fontFace sfnt2FontFace(Handle sfnt)
  43344.     = {0x7019,0xA854}; 
  43345. æDT fontFace myVariable = sfnt2FontFace((Handle) sfnt);
  43346. æRI 
  43347. æC  
  43348.  
  43349. æKY DisposeFontFace
  43350. æFc OutlineCalls.h
  43351. æT Function
  43352. æTN A854
  43353. æD 
  43354. pascal void DisposeFontFace(fontFace theFontFace)
  43355.     = {0x701A,0xA854}; 
  43356. æDT 
  43357. DisposeFontFace((fontFace) theFontFace);
  43358. æRI
  43359. æC  
  43360.  
  43361. æKY GetFontFace
  43362. æFc OutlineCalls.h
  43363. æT Function
  43364. æTN A854
  43365. æD 
  43366. pascal void GetFontFace(fontFace theFontFace,const Str255 fontName)
  43367.     = {0x701B,0xA854}; 
  43368. æDT 
  43369. GetFontFace((fontFace) theFontFace,(const Str255) fontName);
  43370. æRI 
  43371. æC  
  43372.  
  43373. æKY DetachFontFace
  43374. æFc OutlineCalls.h
  43375. æT Function
  43376. æTN A854
  43377. æD 
  43378. pascal void DetachFontFace(fontFace theFontFace)
  43379.     = {0x701C,0xA854}; 
  43380. æDT 
  43381. DetachFontFace((fontFace) theFontFace);
  43382. æRI 
  43383. æC  
  43384.  
  43385. æKY CountFontTables
  43386. æFc OutlineCalls.h
  43387. æT Function
  43388. æTN A854
  43389. æD 
  43390. pascal long CountFontTables(fontFace theFontFace)
  43391.     = {0x701D,0xA854}; 
  43392. æDT long myVariable = CountFontTables((fontFace) theFontFace);
  43393. æRI 
  43394. æC  
  43395.  
  43396. æKY GetFontTableInfo
  43397. æFc OutlineCalls.h
  43398. æT Function
  43399. æTN A854
  43400. æD 
  43401. pascal long GetFontTableInfo(fontFace theFontFace,long index,tableTag* theTableTag,
  43402.     long* checkSum)
  43403.     = {0x701E,0xA854}; 
  43404. æDT long myVariable = GetFontTableInfo((fontFace) theFontFace,(long) index,(tableTag*) theTableTag,()
  43405.     long* checkSum);
  43406. æRI 
  43407. æC  
  43408.  
  43409. æKY GetFontTable
  43410. æFc OutlineCalls.h
  43411. æT Function
  43412. æTN A854
  43413. æD 
  43414. pascal long GetFontTable(fontFace theFontFace,long index,Ptr userCopy)
  43415.     = {0x701F,0xA854}; 
  43416. æDT long myVariable = GetFontTable((fontFace) theFontFace,(long) index,(Ptr) userCopy);
  43417. æRI 
  43418. æC  
  43419.  
  43420. æKY GetFontTablePart
  43421. æFc OutlineCalls.h
  43422. æT Function
  43423. æTN A854
  43424. æD 
  43425. pascal void GetFontTablePart(fontFace theFontFace,long index,long offset,
  43426.     long length,Ptr userCopy)
  43427.     = {0x7020,0xA854}; 
  43428. æDT 
  43429. GetFontTablePart((fontFace) theFontFace,(long) index,(long) offset,()
  43430.     long length,(Ptr) userCopy);
  43431. æRI 
  43432. æC  
  43433.  
  43434. æKY CountFontStrings
  43435. æFc OutlineCalls.h
  43436. æT Function
  43437. æTN A854
  43438. æD 
  43439. pascal long CountFontStrings(fontFace theFontFace)
  43440.     = {0x7021,0xA854}; 
  43441. æDT long myVariable = CountFontStrings((fontFace) theFontFace);
  43442. æRI 
  43443. æC  
  43444.  
  43445. æKY GetFontStringInfo
  43446. æFc OutlineCalls.h
  43447. æT Function
  43448. æTN A854
  43449. æD 
  43450. pascal long GetFontStringInfo(fontFace theFontFace,fontStringInfo* theFontStringInfo)
  43451.     = {0x7022,0xA854}; 
  43452. æDT long myVariable = GetFontStringInfo((fontFace) theFontFace,(fontStringInfo*) theFontStringInfo);
  43453. æRI 
  43454. æC  
  43455.  
  43456. æKY GetFontString
  43457. æFc OutlineCalls.h
  43458. æT Function
  43459. æTN A854
  43460. æD 
  43461. pascal long GetFontString(fontFace theFontFace,Ptr userCopy)
  43462.     = {0x7023,0xA854}; 
  43463. æDT long myVariable = GetFontString((fontFace) theFontFace,(Ptr) userCopy);
  43464. æRI 
  43465. æC  
  43466.  
  43467. æKY CountFontMappings
  43468. æFc OutlineCalls.h
  43469. æT Function
  43470. æTN A854
  43471. æD 
  43472. pascal long CountFontMappings(fontFace theFontFace)
  43473.     = {0x7024,0xA854}; 
  43474. æDT long myVariable = CountFontMappings((fontFace) theFontFace);
  43475. æRI 
  43476. æC  
  43477.  
  43478. æKY GetFontMappingInfo
  43479. æFc OutlineCalls.h
  43480. æT Function
  43481. æTN A854
  43482. æD 
  43483. pascal long GetFontMappingInfo(fontFace theFontFace,long index,short* platform,
  43484.     short* specific)
  43485.     = {0x7025,0xA854}; 
  43486. æDT long myVariable = GetFontMappingInfo((fontFace) theFontFace,(long) index,(short*) platform,()
  43487.     short* specific);
  43488. æRI 
  43489. æC  
  43490.  
  43491. æKY ApplyFontMapping
  43492. æFc OutlineCalls.h
  43493. æT Function
  43494. æTN A854
  43495. æD 
  43496. pascal long ApplyFontMapping(fontFace theFontFace,long index,Ptr textStream,
  43497.     short* glyphs,long count)
  43498.     = {0x7026,0xA854}; 
  43499. æDT long myVariable = ApplyFontMapping((fontFace) theFontFace,(long) index,(Ptr) textStream,()
  43500.     short* glyphs,(long) count);
  43501. æRI
  43502. æC  
  43503.  
  43504. æKY CountFontGlyphs
  43505. æFc OutlineCalls.h
  43506. æT Function
  43507. æTN A854
  43508. æD 
  43509. pascal long CountFontGlyphs(fontFace theFontFace)
  43510.     = {0x7027,0xA854}; 
  43511. æDT long myVariable = CountFontGlyphs((fontFace) theFontFace);
  43512. æRI 
  43513. æC  
  43514.  
  43515. æKY GetGlyphPSName
  43516. æFc OutlineCalls.h
  43517. æT Function
  43518. æTN A854
  43519. æD 
  43520. pascal long GetGlyphPSName(fontFace theFontFace,long index,const Str255 psName)
  43521.     = {0x7028,0xA854}; 
  43522. æDT long myVariable = GetGlyphPSName((fontFace) theFontFace,(long) index,(const Str255) psName);
  43523. æRI 
  43524. æC  
  43525.  
  43526. æKY GetAllGlyphPSNames
  43527. æFc OutlineCalls.h
  43528. æT Function
  43529. æTN A854
  43530. æD 
  43531. pascal void GetAllGlyphPSNames(fontFace theFontFace,Handle names)
  43532.     = {0x7029,0xA854}; 
  43533. æDT 
  43534. GetAllGlyphPSNames((fontFace) theFontFace,(Handle) names);
  43535. æRI 
  43536. æC  
  43537.  
  43538. æKY Packages.h
  43539. æKL InitAllPacks
  43540. InitPack
  43541. IUClearCache
  43542. IUCompPString
  43543. IUCompString
  43544. iucompstring
  43545. IUDatePString
  43546. iudatepstring
  43547. iudatestring
  43548. IUDateString
  43549. IUEqualPString
  43550. IUEqualString
  43551. iuequalstring
  43552. IUGetIntl
  43553. IUGetItlTable
  43554. IULangOrder
  43555. IUMagIDPString
  43556. IUMagIDString
  43557. IUMagPString
  43558. IUMagString
  43559. IUMetric
  43560. IUScriptOrder
  43561. IUSetIntl
  43562. IUStringOrder
  43563. IUTextOrder
  43564. IUTimePString
  43565. iutimepstring
  43566. iutimestring
  43567. IUTimeString
  43568. numtostring
  43569. NumToString
  43570. stringtonum
  43571. StringToNum
  43572.  
  43573. abbrevDate
  43574. bdConv
  43575. century
  43576. currLeadingZ
  43577. currNegSym
  43578. currSymLead
  43579. currTrailingZ
  43580. DateForm
  43581. DateOrders
  43582. dayLdingZ
  43583. dmy
  43584. dskInit
  43585. dym
  43586. editionMgr
  43587. flPoint
  43588. hrLeadingZ
  43589. Intl0Hndl
  43590. Intl0Ptr
  43591. Intl0Rec
  43592. Intl1Hndl
  43593. Intl1Ptr
  43594. Intl1Rec
  43595. intUtil
  43596. iuCurrentCurLang
  43597. iuCurrentDefLang
  43598. iuCurrentScript
  43599. iuNumberPartsTable
  43600. iuScriptCurLang
  43601. iuScriptDefLang
  43602. iuSystemCurLang
  43603. iuSystemDefLang
  43604. iuSystemScript
  43605. iuWordSelectTable
  43606. iuWordWrapTable
  43607. LangCode
  43608. listMgr
  43609. longDate
  43610. longDay
  43611. longMonth
  43612. longWeek
  43613. longYear
  43614. maxCountry
  43615. mdy
  43616. minCountry
  43617. minLeadingZ
  43618. mntLdingZ
  43619. myd
  43620. ScriptCode
  43621. secLeadingZ
  43622. shortDate
  43623. stdFile
  43624. supDay
  43625. supMonth
  43626. supWeek
  43627. supYear
  43628. trFunc
  43629. verArabia
  43630. verArabic
  43631. verAustralia
  43632. verBelgiumLux
  43633. verBritain
  43634. verChina
  43635. verCyprus
  43636. verDenmark
  43637. verEstonia
  43638. verFaeroeIsl
  43639. verFinland
  43640. verFrance
  43641. verFrCanada
  43642. verFrSwiss
  43643. verGermany
  43644. verGreece
  43645. verGrSwiss
  43646. verHungary
  43647. verIceland
  43648. verIndia
  43649. verIran
  43650. verIreland
  43651. verIsrael
  43652. verItaly
  43653. verJapan
  43654. verKorea
  43655. verLapland
  43656. verLatvia
  43657. verLithuania
  43658. verMalta
  43659. verNetherlands
  43660. verNorway
  43661. verPakistan
  43662. verPoland
  43663. verPortugal
  43664. verRussia
  43665. verSpain
  43666. verSweden
  43667. verTaiwan
  43668. verThailand
  43669. verTurkey
  43670. verUS
  43671. verYugoslavia
  43672. ydm
  43673. ymd
  43674. zeroCycle
  43675.  
  43676. æKY listMgr
  43677. æFc Packages.h
  43678. æT #define
  43679. æD #define listMgr 0 /*list manager*/
  43680. æC 
  43681.  
  43682.   /* Resource IDs for packages */
  43683.  
  43684. #define  listMgr     0    /*List Manager*/
  43685. #define  dskInit     2    /*Disk Initialization*/
  43686. #define  stdFile     3    /*Standard File*/
  43687. #define  flPoint     4    /*Floating-Point Arithmetic*/
  43688. #define  trFunc      5    /*Transcendental Functions*/
  43689. #define  intUtil     6    /*International Utilities*/
  43690. #define  bdConv      7    /*Binary-Decimal Conversion*/
  43691. _______________________________________________________________________________
  43692.  
  43693. »ABOUT PACKAGES
  43694. _______________________________________________________________________________
  43695.  
  43696. Packages are sets of data types and routines that are stored as resources and brought
  43697. into memory only when needed. They serve as extensions to the Toolbox and Operating
  43698. System, for the most part performing less common operations.
  43699.  
  43700. The Macintosh packages, which are stored in the system resource file, include the
  43701. following:
  43702.  
  43703.   •  The Standard File Package, for presenting the standard user interface
  43704.      when a file is to be saved or opened.
  43705.   •  The Disk Initialization Package, for initializing and naming new disks.
  43706.      This package is called by the Standard File Package; you’ll only need
  43707.      to call it in nonstandard situations.
  43708.   •  The International Utilities Package, for accessing country-dependent
  43709.      information such as the formats for numbers, currency, dates, and times.
  43710.   •  The Binary-Decimal Conversion Package, for converting integers to
  43711.      decimal strings and vice versa.
  43712.   •  The Floating-Point Arithmetic Package, which supports extended-precision
  43713.      arithmetic according to IEEE Standard 754.
  43714.   •  The Transcendental Functions Package, which contains trigonometric,
  43715.      logarithmic, exponential, and financial functions, as well as a random
  43716.      number generator.
  43717.   •  The List Manager Package, for creating, displaying, and manipulating lists.
  43718.  
  43719. The following Macintosh packages, previously stored only in the system resource file,
  43720. are now also found in the 128K ROM:
  43721.  
  43722.   •  The Binary-Decimal Conversion Package
  43723.   •  The Floating-Point Arithmetic Package
  43724.   •  The Transcendental Functions Package
  43725.  
  43726. For compatibility with the 64K ROM, the above resources are still stored in the
  43727. system resource file. The system resource file contains the following additional
  43728. packages as well:
  43729.  
  43730.   •  The List Manager Package, for creating, displaying, and manipulating lists.
  43731.   •  The Standard File Package.
  43732.   •  The Disk Initialization Package
  43733.   •  The International Utilities Package
  43734.  
  43735. Packages have the resource type 'PACK' and the following resource IDs:
  43736.  
  43737. CONST  listMgr = 0;    {List Manager}
  43738.        dskInit = 2;    {Disk Initialization}
  43739.        stdFile = 3;    {Standard File}
  43740.        flPoint = 4;    {Floating-Point Arithmetic}
  43741.        trFunc  = 5;    {Transcendental Functions}
  43742.        intUtil = 6;    {International Utilities}
  43743.        bdConv  = 7;    {Binary-Decimal Conversion}
  43744.  
  43745. The Package Manager has been extended to allow for eight additional packages. All
  43746. packages are reserved for use by Apple.
  43747.  
  43748. Assembly-language note:  Just as for the routines in ROM, you can invoke a
  43749.                          package routine with a macro that has the same name
  43750.                          as the routine preceded by an underscore. These
  43751.                          macros, however, aren’t trap macros themselves;
  43752.                          instead, they expand to invoke the trap macro _PackN,
  43753.                          where N is the resource ID of the package. The package
  43754.                          determines which routine to execute from the routine
  43755.                          selector, an integer that’s passed to it in a word on
  43756.                          the stack. For example, the routine selector for the
  43757.                          Standard File Package procedure SFPutFile is 1, so
  43758.                          invoking the macro _SFPutFile pushes 1 onto the stack
  43759.                          and invokes _Pack3. The routines in the Floating-Point
  43760.                          Arithmetic and Transcendental Functions packages also
  43761.                          invoke a trap macro of the form _PackN, but the
  43762.                          mechanism through which they’re called is somewhat
  43763.                          different, as explained in the chapter describing
  43764.                          those packages.
  43765.  
  43766. æKY dskInit
  43767. æFc Packages.h
  43768. æT #define
  43769. æD #define dskInit 2 /*Disk Initializaton*/
  43770. æC 
  43771.  
  43772. æKY stdFile
  43773. æFc Packages.h
  43774. æT #define
  43775. æD #define stdFile 3 /*Standard File*/
  43776. æC 
  43777.  
  43778. æKY flPoint
  43779. æFc Packages.h
  43780. æT #define
  43781. æD #define flPoint 4 /*Floating-Point Arithmetic*/
  43782. æC 
  43783.  
  43784. æKY trFunc
  43785. æFc Packages.h
  43786. æT #define
  43787. æD #define trFunc 5 /*Transcendental Functions*/
  43788. æC 
  43789.  
  43790. æKY intUtil
  43791. æFc Packages.h
  43792. æT #define
  43793. æD #define intUtil 6 /*International Utilities*/
  43794. æC 
  43795.  
  43796. æKY bdConv
  43797. æFc Packages.h
  43798. æT #define
  43799. æD #define bdConv 7 /*Binary/Decimal Conversion*/
  43800. æC 
  43801.  
  43802. æKY editionMgr
  43803. æFc Packages.h
  43804. æT #define
  43805. æD #define editionMgr 11 /*Ediiton Manager*/
  43806. æC 
  43807.  
  43808. æKY currSymLead
  43809. æFc Packages.h
  43810. æT #define
  43811. æD #define currSymLead 16
  43812. æC 
  43813.  
  43814. æKY currNegSym
  43815. æFc Packages.h
  43816. æT #define
  43817. æD #define currNegSym 32
  43818. æC 
  43819.  
  43820. æKY currTrailingZ
  43821. æFc Packages.h
  43822. æT #define
  43823. æD #define currTrailingZ 64
  43824. æC 
  43825.  
  43826. æKY currLeadingZ
  43827. æFc Packages.h
  43828. æT #define
  43829. æD #define currLeadingZ 128
  43830. æC 
  43831.  
  43832. æKY zeroCycle
  43833. æFc Packages.h
  43834. æT #define
  43835. æD #define zeroCycle 1 /*0:00 AM/PM format*/
  43836. æC 
  43837.  
  43838. æKY longDay
  43839. æFc Packages.h
  43840. æT #define
  43841. æD #define longDay 0 /*day of the month*/
  43842. æC 
  43843.  
  43844. æKY longWeek
  43845. æFc Packages.h
  43846. æT #define
  43847. æD #define longWeek 1 /*day of the week*/
  43848. æC 
  43849.  
  43850. æKY longMonth
  43851. æFc Packages.h
  43852. æT #define
  43853. æD #define longMonth 2 /*month of the year*/
  43854. æC 
  43855.  
  43856. æKY longYear
  43857. æFc Packages.h
  43858. æT #define
  43859. æD #define longYear 3 /*year*/
  43860. æC 
  43861.  
  43862. æKY supDay
  43863. æFc Packages.h
  43864. æT #define
  43865. æD #define supDay 1 /*suppress day of month*/
  43866. æC 
  43867.  
  43868. æKY supWeek
  43869. æFc Packages.h
  43870. æT #define
  43871. æD #define supWeek 2 /*suppress day of week*/
  43872. æC 
  43873.  
  43874. æKY supMonth
  43875. æFc Packages.h
  43876. æT #define
  43877. æD #define supMonth 4 /*suppress month*/
  43878. æC 
  43879.  
  43880. æKY supYear
  43881. æFc Packages.h
  43882. æT #define
  43883. æD #define supYear 8 /*suppress year*/
  43884. æC 
  43885.  
  43886. æKY dayLdingZ
  43887. æFc Packages.h
  43888. æT #define
  43889. æD #define dayLdingZ 32
  43890. æC 
  43891.  
  43892. æKY mntLdingZ
  43893. æFc Packages.h
  43894. æT #define
  43895. æD #define mntLdingZ 64
  43896. æC 
  43897.  
  43898. æKY century
  43899. æFc Packages.h
  43900. æT #define
  43901. æD #define century 128
  43902. æC 
  43903.  
  43904. æKY secLeadingZ
  43905. æFc Packages.h
  43906. æT #define
  43907. æD #define secLeadingZ 32
  43908. æC 
  43909.  
  43910. æKY minLeadingZ
  43911. æFc Packages.h
  43912. æT #define
  43913. æD #define minLeadingZ 64
  43914. æC 
  43915.  
  43916. æKY hrLeadingZ
  43917. æFc Packages.h
  43918. æT #define
  43919. æD #define hrLeadingZ 128
  43920. æC 
  43921.  
  43922. æKY verUS
  43923. æFc Packages.h
  43924. æT #define
  43925. æD 
  43926. /* Country Version */
  43927.  
  43928. #define verUS 0
  43929. æC 
  43930.  
  43931. æKY verFrance
  43932. æFc Packages.h
  43933. æT #define
  43934. æD #define verFrance 1
  43935. æC 
  43936.  
  43937. æKY verBritain
  43938. æFc Packages.h
  43939. æT #define
  43940. æD #define verBritain 2
  43941. æC 
  43942.  
  43943. æKY verGermany
  43944. æFc Packages.h
  43945. æT #define
  43946. æD #define verGermany 3
  43947. æC 
  43948.  
  43949. æKY verItaly
  43950. æFc Packages.h
  43951. æT #define
  43952. æD #define verItaly 4
  43953. æC 
  43954.  
  43955. æKY verNetherlands
  43956. æFc Packages.h
  43957. æT #define
  43958. æD #define verNetherlands 5
  43959. æC 
  43960.  
  43961. æKY verBelgiumLux
  43962. æFc Packages.h
  43963. æT #define
  43964. æD #define verBelgiumLux 6
  43965. æC 
  43966.  
  43967. æKY verSweden
  43968. æFc Packages.h
  43969. æT #define
  43970. æD #define verSweden 7
  43971. æC 
  43972.  
  43973. æKY verSpain
  43974. æFc Packages.h
  43975. æT #define
  43976. æD #define verSpain 8
  43977. æC 
  43978.  
  43979. æKY verDenmark
  43980. æFc Packages.h
  43981. æT #define
  43982. æD #define verDenmark 9
  43983. æC 
  43984.  
  43985. æKY verPortugal
  43986. æFc Packages.h
  43987. æT #define
  43988. æD #define verPortugal 10
  43989. æC 
  43990.  
  43991. æKY verFrCanada
  43992. æFc Packages.h
  43993. æT #define
  43994. æD #define verFrCanada 11
  43995. æC 
  43996.  
  43997. æKY verNorway
  43998. æFc Packages.h
  43999. æT #define
  44000. æD #define verNorway 12
  44001. æC 
  44002.  
  44003. æKY verIsrael
  44004. æFc Packages.h
  44005. æT #define
  44006. æD #define verIsrael 13
  44007. æC 
  44008.  
  44009. æKY verJapan
  44010. æFc Packages.h
  44011. æT #define
  44012. æD #define verJapan 14
  44013. æC 
  44014.  
  44015. æKY verAustralia
  44016. æFc Packages.h
  44017. æT #define
  44018. æD #define verAustralia 15
  44019. æC 
  44020.  
  44021. æKY verArabia
  44022. æFc Packages.h
  44023. æT #define
  44024. æD #define verArabia 16
  44025. æC 
  44026.  
  44027. æKY verArabic
  44028. æFc Packages.h
  44029. æT #define
  44030. æD #define verArabic 16
  44031. æC 
  44032.  
  44033. æKY verFinland
  44034. æFc Packages.h
  44035. æT #define
  44036. æD #define verFinland 17
  44037. æC 
  44038.  
  44039. æKY verFrSwiss
  44040. æFc Packages.h
  44041. æT #define
  44042. æD #define verFrSwiss 18
  44043. æC 
  44044.  
  44045. æKY verGrSwiss
  44046. æFc Packages.h
  44047. æT #define
  44048. æD #define verGrSwiss 19
  44049. æC 
  44050.  
  44051. æKY verGreece
  44052. æFc Packages.h
  44053. æT #define
  44054. æD #define verGreece 20
  44055. æC 
  44056.  
  44057. æKY verIceland
  44058. æFc Packages.h
  44059. æT #define
  44060. æD #define verIceland 21
  44061. æC 
  44062.  
  44063. æKY verMalta
  44064. æFc Packages.h
  44065. æT #define
  44066. æD #define verMalta 22
  44067. æC 
  44068.  
  44069. æKY verCyprus
  44070. æFc Packages.h
  44071. æT #define
  44072. æD #define verCyprus 23
  44073. æC 
  44074.  
  44075. æKY verTurkey
  44076. æFc Packages.h
  44077. æT #define
  44078. æD #define verTurkey 24
  44079. æC 
  44080.  
  44081. æKY verYugoslavia
  44082. æFc Packages.h
  44083. æT #define
  44084. æD #define verYugoslavia 25
  44085. æC 
  44086.  
  44087. æKY verIndia
  44088. æFc Packages.h
  44089. æT #define
  44090. æD #define verIndia 33
  44091. æC 
  44092.  
  44093. æKY verPakistan
  44094. æFc Packages.h
  44095. æT #define
  44096. æD #define verPakistan 34
  44097. æC 
  44098.  
  44099. æKY verLithuania
  44100. æFc Packages.h
  44101. æT #define
  44102. æD #define verLithuania 41
  44103. æC 
  44104.  
  44105. æKY verPoland
  44106. æFc Packages.h
  44107. æT #define
  44108. æD #define verPoland 42
  44109. æC 
  44110.  
  44111. æKY verHungary
  44112. æFc Packages.h
  44113. æT #define
  44114. æD #define verHungary 43
  44115. æC 
  44116.  
  44117. æKY verEstonia
  44118. æFc Packages.h
  44119. æT #define
  44120. æD #define verEstonia 44
  44121. æC 
  44122.  
  44123. æKY verLatvia
  44124. æFc Packages.h
  44125. æT #define
  44126. æD #define verLatvia 45
  44127. æC 
  44128.  
  44129. æKY verLapland
  44130. æFc Packages.h
  44131. æT #define
  44132. æD #define verLapland 46
  44133. æC 
  44134.  
  44135. æKY verFaeroeIsl
  44136. æFc Packages.h
  44137. æT #define
  44138. æD #define verFaeroeIsl 47
  44139. æC 
  44140.  
  44141. æKY verIran
  44142. æFc Packages.h
  44143. æT #define
  44144. æD #define verIran 48
  44145. æC 
  44146.  
  44147. æKY verRussia
  44148. æFc Packages.h
  44149. æT #define
  44150. æD #define verRussia 49
  44151. æC 
  44152.  
  44153. æKY verIreland
  44154. æFc Packages.h
  44155. æT #define
  44156. æD #define verIreland 50
  44157. æC 
  44158.  
  44159. æKY verKorea
  44160. æFc Packages.h
  44161. æT #define
  44162. æD #define verKorea 51
  44163. æC 
  44164.  
  44165. æKY verChina
  44166. æFc Packages.h
  44167. æT #define
  44168. æD #define verChina 52
  44169. æC 
  44170.  
  44171. æKY verTaiwan
  44172. æFc Packages.h
  44173. æT #define
  44174. æD #define verTaiwan 53
  44175. æC 
  44176.  
  44177. æKY verThailand
  44178. æFc Packages.h
  44179. æT #define
  44180. æD #define verThailand 54
  44181. æC 
  44182.  
  44183. æKY minCountry
  44184. æFc Packages.h
  44185. æT #define
  44186. æD #define minCountry verUS
  44187. æC 
  44188.  
  44189. æKY maxCountry
  44190. æFc Packages.h
  44191. æT #define
  44192. æD #define maxCountry verThailand
  44193. æC 
  44194.  
  44195. æKY iuSystemScript
  44196. æFc Packages.h
  44197. æT #define
  44198. æD 
  44199. /* special ScriptCode values */
  44200.  
  44201. #define iuSystemScript (-1) /* system script */
  44202. æC 
  44203.  
  44204. æKY iuCurrentScript
  44205. æFc Packages.h
  44206. æT #define
  44207. æD #define iuCurrentScript (-2) /* current script */
  44208. æC 
  44209.  
  44210. æKY iuSystemCurLang
  44211. æFc Packages.h
  44212. æT #define
  44213. æD 
  44214. /* special LangCode values */
  44215.  
  44216. #define iuSystemCurLang (-2) /* current (itlbLang) lang for system script */
  44217. æC 
  44218.  
  44219. æKY iuSystemDefLang
  44220. æFc Packages.h
  44221. æT #define
  44222. æD #define iuSystemDefLang (-3) /* default (table) lang for system script */
  44223. æC 
  44224.  
  44225. æKY iuCurrentCurLang
  44226. æFc Packages.h
  44227. æT #define
  44228. æD #define iuCurrentCurLang (-4) /* current (itlbLang) lang for current script */
  44229. æC 
  44230.  
  44231. æKY iuCurrentDefLang
  44232. æFc Packages.h
  44233. æT #define
  44234. æD #define iuCurrentDefLang (-5) /* default lang for current script */
  44235. æC 
  44236.  
  44237. æKY iuScriptCurLang
  44238. æFc Packages.h
  44239. æT #define
  44240. æD #define iuScriptCurLang (-6) /* current (itlbLang) lang for specified script */
  44241. æC 
  44242.  
  44243. æKY iuScriptDefLang
  44244. æFc Packages.h
  44245. æT #define
  44246. æD #define iuScriptDefLang (-7) /* default language for a specified script */
  44247. æC 
  44248.  
  44249. æKY iuWordSelectTable
  44250. æFc Packages.h
  44251. æT #define
  44252. æD 
  44253. /* table selectors for IUGetItlTable */
  44254.  
  44255. #define iuWordSelectTable 0
  44256. æC 
  44257.  
  44258. æKY iuWordWrapTable
  44259. æFc Packages.h
  44260. æT #define
  44261. æD #define iuWordWrapTable 1
  44262. æC 
  44263.  
  44264. æKY iuNumberPartsTable
  44265. æFc Packages.h
  44266. æT #define
  44267. æD #define iuNumberPartsTable 2
  44268. æC 
  44269.  
  44270. æKY DateForm
  44271. shortDate
  44272. longDate
  44273. abbrevDate
  44274. æFc Packages.h
  44275. æT enum
  44276. æD enum {shortDate,longDate,abbrevDate};
  44277. typedef unsigned char DateForm;
  44278. æC 
  44279.  
  44280. æKY DateOrders
  44281. mdy
  44282. dmy
  44283. ymd
  44284. myd
  44285. dym
  44286. ydm
  44287. æFc Packages.h
  44288. æT enum
  44289. æD enum {mdy,dmy,ymd,myd,dym,ydm};
  44290. typedef unsigned char DateOrders;
  44291. æC 
  44292.  
  44293. æKY ScriptCode
  44294. æFc Packages.h
  44295. æT typedef
  44296. æD  typedef short ScriptCode;
  44297. æC 
  44298.  
  44299. æKY LangCode
  44300. æFc Packages.h
  44301. æT typedef
  44302. æD  typedef short LangCode;
  44303. æC 
  44304.  
  44305. æKY Intl0Rec
  44306. Intl0Ptr
  44307. Intl0Hndl
  44308. æFc Packages.h
  44309. æT struct
  44310. æD struct Intl0Rec {
  44311.     char decimalPt; /*decimal point character*/
  44312.     char thousSep; /*thousands separator*/
  44313.     char listSep; /*list separator*/
  44314.     char currSym1; /*currency symbol*/
  44315.     char currSym2;
  44316.     char currSym3;
  44317.     unsigned char currFmt; /*currency format*/
  44318.     unsigned char dateOrder; /*order of short date elements*/
  44319.     unsigned char shrtDateFmt; /*short date format*/
  44320.     char dateSep; /*date separator*/
  44321.     unsigned char timeCycle; /*0 if 24-hour cycle, 255 if 12-hour*/
  44322.     unsigned char timeFmt; /*time format*/
  44323.     char mornStr[4]; /*trailing string for first 12-hour cycle*/
  44324.     char eveStr[4]; /*trailing string for last 12-hour cycle*/
  44325.     char timeSep; /*time separator*/
  44326.     char time1Suff; /*trailing string for 24-hour cycle*/
  44327.     char time2Suff;
  44328.     char time3Suff;
  44329.     char time4Suff;
  44330.     char time5Suff;
  44331.     char time6Suff;
  44332.     char time7Suff;
  44333.     char time8Suff;
  44334.     unsigned char metricSys; /*255 if metric, 0 if not*/
  44335.     short intl0Vers; /*version information*/
  44336. };
  44337.  
  44338. typedef struct Intl0Rec Intl0Rec;
  44339. typedef Intl0Rec *Intl0Ptr, **Intl0Hndl;
  44340.  
  44341. æC 
  44342.  
  44343. æKY Intl1Rec
  44344. Intl1Ptr
  44345. Intl1Hndl
  44346. æFc Packages.h
  44347. æT struct
  44348. æD struct Intl1Rec {
  44349.     Str15 days[7]; /*day names*/
  44350.     Str15 months[12]; /*month names*/
  44351.     unsigned char suppressDay; /*0 for day name, 255 for none*/
  44352.     unsigned char lngDateFmt; /*order of long date elements*/
  44353.     unsigned char dayLeading0; /*255 for leading 0 in day number*/
  44354.     unsigned char abbrLen; /*length for abbreviating names*/
  44355.     char st0[4]; /*strings for long date format*/
  44356.     char st1[4];
  44357.     char st2[4];
  44358.     char st3[4];
  44359.     char st4[4];
  44360.     short intl1Vers; /*version information*/
  44361.     short localRtn[1]; /*routine for localizing string comparison*/
  44362. };
  44363.  
  44364. typedef struct Intl1Rec Intl1Rec;
  44365. typedef Intl1Rec *Intl1Ptr, **Intl1Hndl;
  44366.  
  44367. æC 
  44368.  
  44369. æKY InitPack
  44370. æFc Packages.h
  44371. æT Function
  44372. æTN A9E5
  44373. æD pascal void InitPack(short packID)
  44374.     = 0xA9E5; 
  44375. æDT InitPack((short) packID);
  44376. æMM
  44377. æRI I-484
  44378. æC  
  44379. InitPack enables you to use the package specified by packID, which is the package’s
  44380. resource ID. (It gets a handle that will be used later to read the package into
  44381. memory.)
  44382.  
  44383. æKY InitAllPacks
  44384. æFc Packages.h
  44385. æT Function
  44386. æTN A9E6
  44387. æD pascal void InitAllPacks(void)
  44388.     = 0xA9E6; 
  44389. æDT InitAllPacks()(void);
  44390. æMM
  44391. æRI I-484
  44392. æC 
  44393. InitAllPacks enables you to use all Macintosh packages (as though InitPack were
  44394. called for each one). It will already have been called when your application starts
  44395. up.
  44396.  
  44397. æKY IUGetIntl
  44398. æFc Packages.h
  44399. æT Function
  44400. æD pascal Handle IUGetIntl(short theID)
  44401.     = {0x3F3C,0x0006,0xA9ED}; 
  44402. æDT Handle myVariable = IUGetIntl((short) theID);
  44403. æMM
  44404. æRT 153
  44405. æRI I-505
  44406. æC     IUGetIntl returns a handle to the international resource numbered
  44407. theID (0 or 1). It calls the Resource Manager function
  44408. GetResource('INTL',theID). For example, if you want to access
  44409. individual fields of international resource 0, you can do the
  44410. following:
  44411.  
  44412.      VAR myHndl: Handle;
  44413.          int0: Intl0Hndl;
  44414.      ...
  44415.      myHndl := IUGetIntl(0);
  44416.      int0 := POINTER(ORD(myHndl));
  44417.  
  44418. æKY IUSetIntl
  44419. æFc Packages.h
  44420. æT Function
  44421. æD pascal void IUSetIntl(short refNum,short theID,Handle intlParam)
  44422.     = {0x3F3C,0x0008,0xA9ED}; 
  44423. æDT IUSetIntl((short) refNum,(short) theID,(Handle) intlParam);
  44424. æMM
  44425. æRI I-506
  44426. æC     In the resource file having the reference number refNum, IUSetIntl
  44427. sets the international resource numbered theID (0 or 1) to the data
  44428. pointed to by intlParam. The data may be either an existing resource
  44429. or data that hasn't yet been written to a resource file. IUSetIntl
  44430. adds the resource to the specified file or replaces the resource if it's
  44431. already there.
  44432.  
  44433. æKY IUDateString
  44434. æFc Packages.h
  44435. æT Function
  44436. æD pascal void IUDateString(long dateTime,DateForm longFlag,Str255 result)
  44437.     = {0x3F3C,0x0000,0xA9ED}; 
  44438. æDT IUDateString((long) dateTime,(DateForm) longFlag,(Str255) result);
  44439. æMM
  44440. æRI I-504
  44441. æC     Given a date and time as returned by the Operating System Utility
  44442. routine ReadDateTime, IUDateString returns in the result parameter a
  44443. string that represents the corresponding date. The form parameter has
  44444. the following data type:
  44445.  
  44446.        TYPE DateForm = (shortDate,longDate,abbrevDate);
  44447.  
  44448.     ShortDate requests the short date format, longDate the long date,
  44449. and abbrevDate the abbreviated long date. IUDateString determines the
  44450. exact format from international resource 0 for the short date or 1 for
  44451. the long date. See Figure I-1 above for examples of the standard
  44452. formats. Notice that the short date contains a space in place of  a
  44453. leading zero when the format specifies "no leading zero", so the length
  44454. of the result is always the same for short dates.
  44455.  
  44456.     If the abbreviated long date is requested and the abbreviation
  44457. length in international resource 1 is greater than the actual length of
  44458. the name being abbreviated, IUDateString fills the abbreviation with NULL
  44459. characters; the abbreviation length should not be greater than 15, the
  44460. maximum name length.
  44461.  
  44462. æKY iudatestring
  44463. æFc Packages.h
  44464. æT Function
  44465. æD void iudatestring(long dateTime,DateForm longFlag,char *result); 
  44466. æDT iudatestring((long) dateTime,(DateForm) longFlag,(char *) result);
  44467. æMM
  44468. æRI I-504
  44469. æC     Given a date and time as returned by the Operating System Utility
  44470. routine ReadDateTime, IUDateString returns in the result parameter a
  44471. string that represents the corresponding date. The form parameter has
  44472. the following data type:
  44473.  
  44474.        TYPE DateForm = (shortDate,longDate,abbrevDate);
  44475.  
  44476.     ShortDate requests the short date format, longDate the long date,
  44477. and abbrevDate the abbreviated long date. IUDateString determines the
  44478. exact format from international resource 0 for the short date or 1 for
  44479. the long date. See Figure I-1 above for examples of the standard
  44480. formats. Notice that the short date contains a space in place of  a
  44481. leading zero when the format specifies "no leading zero", so the length
  44482. of the result is always the same for short dates.
  44483.  
  44484.     If the abbreviated long date is requested and the abbreviation
  44485. length in international resource 1 is greater than the actual length of
  44486. the name being abbreviated, IUDateString fills the abbreviation with NULL
  44487. characters; the abbreviation length should not be greater than 15, the
  44488. maximum name length.
  44489.  
  44490. æKY iudatepstring
  44491. æFc Packages.h
  44492. æT Function
  44493. æD void iudatepstring(long dateTime,DateForm longFlag,char *result,Handle intlParam); 
  44494. æDT iudatepstring((long) dateTime,(DateForm) longFlag,(char *) result,(Handle) intlParam);
  44495. æMM
  44496. æRI I-505
  44497. æC     IUDatePString is the same as IUDateString except that it determines
  44498. the exact format of the date from the resource whose handle is passed in
  44499. intlParam, overriding the resource that would otherwise be used.
  44500.  
  44501. æKY iutimestring
  44502. æFc Packages.h
  44503. æT Function
  44504. æD void iutimestring(long dateTime,Boolean wantSeconds,char *result); 
  44505. æDT iutimestring((long) dateTime,(Boolean) wantSeconds,(char *) result);
  44506. æMM
  44507. æRI I-505
  44508. æC     Given a date and time as returned by the Operating System Utility
  44509. routine ReadDateTime, IUTimeString returns in the result parameter a
  44510. string that represents the corresponding time of day. If wantSeconds
  44511. is TRUE, seconds are included in the time; otherwise, only the hour and
  44512. minute are included. IUTimeSting determines the time format from
  44513. international resource 0. See Figure I-1 above for examples of the
  44514. standard formats. Notice that the time contains a space in place of a
  44515. leading zero when the format specifies "no leading zero", so the length
  44516. of the result is always the same.
  44517.  
  44518. æKY IUDatePString
  44519. æFc Packages.h
  44520. æT Function
  44521. æD pascal void IUDatePString(long dateTime,DateForm longFlag,Str255 result,
  44522.     Handle intlParam)
  44523.     = {0x3F3C,0x000E,0xA9ED}; 
  44524. æDT IUDatePString((long) dateTime,(DateForm) longFlag,(Str255) result,()
  44525.     Handle intlParam);
  44526. æMM
  44527. æRI I-505
  44528. æC     IUDatePString is the same as IUDateString except that it determines
  44529. the exact format of the date from the resource whose handle is passed in
  44530. intlParam, overriding the resource that would otherwise be used.
  44531.  
  44532. æKY iutimepstring
  44533. æFc Packages.h
  44534. æT Function
  44535. æD void iutimepstring(long dateTime,Boolean wantSeconds,char *result,Handle intlParam); 
  44536. æDT iutimepstring((long) dateTime,(Boolean) wantSeconds,(char *) result,(Handle) intlParam);
  44537. æMM
  44538. æRI I-505
  44539. æC     IUTimePString is the same as IUTimeString except that it determines
  44540. the time format from the resource whose handle is passed in intlParam,
  44541. overriding the resource that would otherwise be used.
  44542.  
  44543. æKY IUMetric
  44544. æFc Packages.h
  44545. æT Function
  44546. æD pascal Boolean IUMetric(void)
  44547.     = {0x3F3C,0x0004,0xA9ED}; 
  44548. æDT Boolean myVariable = IUMetric()(void);
  44549. æMM
  44550. æRI I-505
  44551. æC     If international resource 0 specifies that the metric system is to
  44552. be used, IUMetric returns TRUE; otherwise, it returns FALSE.
  44553.  
  44554. æKY IUTimePString
  44555. æFc Packages.h
  44556. æT Function
  44557. æD pascal void IUTimePString(long dateTime,Boolean wantSeconds,Str255 result,
  44558.     Handle intlParam)
  44559.     = {0x3F3C,0x0010,0xA9ED}; 
  44560. æDT IUTimePString((long) dateTime,(Boolean) wantSeconds,(Str255) result,()
  44561.     Handle intlParam);
  44562. æMM
  44563. æRI I-505
  44564. æC     IUTimePString is the same as IUTimeString except that it determines
  44565. the time format from the resource whose handle is passed in intlParam,
  44566. overriding the resource that would otherwise be used.
  44567.  
  44568. æKY IUMagString
  44569. æFc Packages.h
  44570. æT Function
  44571. æD pascal short IUMagString(Ptr aPtr,Ptr bPtr,short aLen,short bLen)
  44572.     = {0x3F3C,0x000A,0xA9ED}; 
  44573. æDT short myVariable = IUMagString((Ptr) aPtr,(Ptr) bPtr,(short) aLen,(short) bLen);
  44574. æMM
  44575. æRI I-506, N58-1
  44576. æC     IUMagString is the same as IUCompString (above) except that instead
  44577. of comparing two Pascal strings, it compares the string defined by aPtr
  44578. and aLen to the string defined by bPtr and bLen. The pointer points to
  44579. the first character of the string (any byte in memory, not necessarily
  44580. word-aligned), and the length specifies the number of characters in the
  44581. string.
  44582.  
  44583. æKY IUTimeString
  44584. æFc Packages.h
  44585. æT Function
  44586. æD pascal void IUTimeString(long dateTime,Boolean wantSeconds,Str255 result)
  44587.     = {0x3F3C,0x0002,0xA9ED}; 
  44588. æDT IUTimeString((long) dateTime,(Boolean) wantSeconds,(Str255) result);
  44589. æMM
  44590. æRI I-505
  44591. æC     Given a date and time as returned by the Operating System Utility
  44592. routine ReadDateTime, IUTimeString returns in the result parameter a
  44593. string that represents the corresponding time of day. If wantSeconds
  44594. is TRUE, seconds are included in the time; otherwise, only the hour and
  44595. minute are included. IUTimeSting determines the time format from
  44596. international resource 0. See Figure I-1 above for examples of the
  44597. standard formats. Notice that the time contains a space in place of a
  44598. leading zero when the format specifies "no leading zero", so the length
  44599. of the result is always the same.
  44600.  
  44601. æKY IUMagIDString
  44602. æFc Packages.h
  44603. æT Function
  44604. æD pascal short IUMagIDString(Ptr aPtr,Ptr bPtr,short aLen,short bLen)
  44605.     = {0x3F3C,0x000C,0xA9ED}; 
  44606. æDT short myVariable = IUMagIDString((Ptr) aPtr,(Ptr) bPtr,(short) aLen,(short) bLen);
  44607. æMM
  44608. æRI I-507, N58-1
  44609. æC IUMagIDString is the same as IUEqualString (above) except that instead of 
  44610. comparing two Pascal strings, it compares the string defined by aPtr and aLen to 
  44611. the string defined by bPtr and bLen.  The pointer points to the first character of the 
  44612. string (any byte in memory, not necessarily word-aligned), and the length specifies 
  44613. the number of characters in the string.
  44614.  
  44615. æKY IUCompString
  44616. æFc Packages.h
  44617. æT Function
  44618. æD pascal short IUCompString(const Str255 aStr,const Str255 bStr); 
  44619. æDT short myVariable = IUCompString((const Str255) aStr,(const Str255) bStr);
  44620. æMM
  44621. æRI I-506, N58-1
  44622. æC     IUCompString compares aStr and bStr as described above under
  44623. "International String Comparison", taking both primary and secondary
  44624. ordering into consideration. It returns one of the values listed
  44625. below.
  44626.  
  44627.       Result   Meaning                           Example
  44628.                                               aStr     bStr
  44629.        -1       aStr is less than bStr       'Ab'     'ab'
  44630.         0       aStr equals bStr             'Ab'     'Ab'
  44631.         1       aStr is greater than bStr    'Ac'     'ab'
  44632.  
  44633. æKY iucompstring
  44634. æFc Packages.h
  44635. æT Function
  44636. æD short iucompstring(char *aStr,char *bStr); 
  44637. æDT short myVariable = iucompstring((char *) aStr,(char *) bStr);
  44638. æC 
  44639.  
  44640. æKY IUEqualString
  44641. æFc Packages.h
  44642. æT Function
  44643. æD pascal short IUEqualString(const Str255 aStr,const Str255 bStr); 
  44644. æDT short myVariable = IUEqualString((const Str255) aStr,(const Str255) bStr);
  44645. æMM
  44646. æRI I-506, N58-1
  44647. æC     IUEqualString compares aStr and bStr for equality without regard
  44648. for secondary ordering, as described above under "international String
  44649. Comparison". If the strings are equal, it returns 0; otherwise, it
  44650. returns 1. For example, if the strings are 'Rose' and 'rose',
  44651. IUEqualString considers them equal and returns 0.
  44652.  
  44653. Note:  
  44654.  
  44655.     See also EqualString in the Operating System Utilities manual.
  44656.  
  44657. æKY iuequalstring
  44658. æFc Packages.h
  44659. æT Function
  44660. æD short iuequalstring(char *aStr,char *bStr); 
  44661. æDT short myVariable = iuequalstring((char *) aStr,(char *) bStr);
  44662. æMM
  44663. æRI I-506, N58-1
  44664. æC     IUEqualString compares aStr and bStr for equality without regard
  44665. for secondary ordering, as described above under "international String
  44666. Comparison". If the strings are equal, it returns 0; otherwise, it
  44667. returns 1. For example, if the strings are 'Rose' and 'rose',
  44668. IUEqualString considers them equal and returns 0.
  44669.  
  44670. Note:  
  44671.  
  44672.     See also EqualString in the Operating System Utilities manual.
  44673.  
  44674. æKY StringToNum
  44675. æFc Packages.h
  44676. æT Function
  44677. æD pascal void StringToNum(const Str255 theString,long *theNum); 
  44678. æDT StringToNum((const Str255) theString,(long *) theNum);
  44679. æMM
  44680. æRI I-490
  44681. æC _____________________________________________________________________________________
  44682.  
  44683. Trap macro     _StringToNum
  44684.  
  44685. On entry       A0:  pointer to theString (length byte followed
  44686.                     by characters)
  44687.  
  44688. On exit        DO:  theNum (long integer)
  44689.  
  44690. _____________________________________________________________________________________
  44691.  
  44692.  
  44693. Given a string representing a decimal integer, StringToNum converts
  44694. it to the corresponding integer and returns the result in theNum. The
  44695. string may begin with a plus or minus sign. For example:
  44696.  
  44697.       theString          theNum
  44698.         '12'               12
  44699.        '-23'              -23
  44700.         '-0'                0
  44701.        '055'               55
  44702.  
  44703.     The magnitude of the integer is converted modulo 2^32, and the
  44704. 32-bit result is negated if the string begins with a minus sign; integer
  44705. overflow occurs if the magnitude is greater than 2^31-1. (Negation is
  44706. done by taking the two's complement--reversing the state of each bit
  44707. and then adding 1.)  For example:
  44708.  
  44709.         theString                                   theNum
  44710.        '2147483648'  (magnitude is 2^31)          -2147483648
  44711.       '-2147483648'                               -2147483648
  44712.        '4294967295'  (magnitude is 2^31)              -1
  44713.       '-4294967295'                                    1
  44714.  
  44715.     StringToNum doesn't actually check whether the characters in the
  44716. string are between '0' and '9'; instead, since the ASCII codes for '0'
  44717. through '9' are $30 through $39, it just masks off the last four bits
  44718. and uses them as a digit. For example, '2:' is converted to the number
  44719. 30 because the ASCI code for ':' is $3A. Leading spaces before the
  44720. first digit are treated as zeroes, since the ASCII code for a space is
  44721. $20. Given that the ASCII codes for 'C', 'A', and 'T' are $43, $41, and
  44722. $54, respectively, consider the following examples:
  44723.  
  44724.  
  44725.       theString              theNum
  44726.         'CAT'                  314
  44727.        '+CAT'                  314
  44728.        '-CAT'                 -314
  44729.  
  44730. æKY stringtonum
  44731. æFc Packages.h
  44732. æT Function
  44733. æD void stringtonum(char *theString,long *theNum); 
  44734. æDT stringtonum((char *) theString,(long *) theNum);
  44735. æMM
  44736. æRI I-490
  44737. æC _____________________________________________________________________________________
  44738.  
  44739. Trap macro     _StringToNum
  44740.  
  44741. On entry       A0:  pointer to theString (length byte followed
  44742.                     by characters)
  44743.  
  44744. On exit        DO:  theNum (long integer)
  44745.  
  44746. _____________________________________________________________________________________
  44747.  
  44748.  
  44749. Given a string representing a decimal integer, StringToNum converts
  44750. it to the corresponding integer and returns the result in theNum. The
  44751. string may begin with a plus or minus sign. For example:
  44752.  
  44753.       theString          theNum
  44754.         '12'               12
  44755.        '-23'              -23
  44756.         '-0'                0
  44757.        '055'               55
  44758.  
  44759.     The magnitude of the integer is converted modulo 2^32, and the
  44760. 32-bit result is negated if the string begins with a minus sign; integer
  44761. overflow occurs if the magnitude is greater than 2^31-1. (Negation is
  44762. done by taking the two's complement--reversing the state of each bit
  44763. and then adding 1.)  For example:
  44764.  
  44765.         theString                                   theNum
  44766.        '2147483648'  (magnitude is 2^31)          -2147483648
  44767.       '-2147483648'                               -2147483648
  44768.        '4294967295'  (magnitude is 2^31)              -1
  44769.       '-4294967295'                                    1
  44770.  
  44771.     StringToNum doesn't actually check whether the characters in the
  44772. string are between '0' and '9'; instead, since the ASCII codes for '0'
  44773. through '9' are $30 through $39, it just masks off the last four bits
  44774. and uses them as a digit. For example, '2:' is converted to the number
  44775. 30 because the ASCI code for ':' is $3A. Leading spaces before the
  44776. first digit are treated as zeroes, since the ASCII code for a space is
  44777. $20. Given that the ASCII codes for 'C', 'A', and 'T' are $43, $41, and
  44778. $54, respectively, consider the following examples:
  44779.  
  44780.  
  44781.       theString              theNum
  44782.         'CAT'                  314
  44783.        '+CAT'                  314
  44784.        '-CAT'                 -314
  44785.  
  44786. æKY NumToString
  44787. æFc Packages.h
  44788. æT Function
  44789. æD pascal void NumToString(long theNum,Str255 theString); 
  44790. æDT NumToString((long) theNum,(Str255) theString);
  44791. æMM
  44792. æRI I-489
  44793. æC _____________________________________________________________________________________
  44794.  
  44795. Trap macro     _NumToString
  44796.  
  44797. On entry        A0:  pointer to theString (length byte followed
  44798.                      by characters)
  44799.  
  44800.                 D0:  theNum (long integer)
  44801.  
  44802. On exit         A0:  pointer to theString
  44803.  
  44804. _____________________________________________________________________________________
  44805.  
  44806. NumToString converts theNum to a string that represents its decimal
  44807. value, and returns the result in theString. If the value is negative,
  44808. the string begins with a minus sign; otherwise, the sign is omitted.
  44809. Leading zeroes are suppressed, except that the value 0 produces '0'.
  44810. For example:
  44811.  
  44812.      theNum          theString
  44813.       12              '12'
  44814.      -23             '-23'
  44815.        0              '0'
  44816.  
  44817. æKY numtostring
  44818. æFc Packages.h
  44819. æT Function
  44820. æD void numtostring(long theNum,char *theString); 
  44821. æDT numtostring((long) theNum,(char *) theString);
  44822. æMM
  44823. æRI I-489
  44824. æC _____________________________________________________________________________________
  44825.  
  44826. Trap macro     _NumToString
  44827.  
  44828. On entry        A0:  pointer to theString (length byte followed
  44829.                      by characters)
  44830.  
  44831.                 D0:  theNum (long integer)
  44832.  
  44833. On exit         A0:  pointer to theString
  44834.  
  44835. _____________________________________________________________________________________
  44836.  
  44837. NumToString converts theNum to a string that represents its decimal
  44838. value, and returns the result in theString. If the value is negative,
  44839. the string begins with a minus sign; otherwise, the sign is omitted.
  44840. Leading zeroes are suppressed, except that the value 0 produces '0'.
  44841. For example:
  44842.  
  44843.      theNum          theString
  44844.       12              '12'
  44845.      -23             '-23'
  44846.        0              '0'
  44847.  
  44848. æKY IUClearCache
  44849. æFc Packages.h
  44850. æT Function
  44851. æD pascal void IUClearCache(void)
  44852.     = {0x3F3C,0x0018,0xA9ED}; 
  44853. æDT IUClearCache()(void);
  44854. æC 
  44855.  
  44856. æKY IUMagPString
  44857. æFc Packages.h
  44858. æT Function
  44859. æD pascal short IUMagPString(Ptr aPtr,Ptr bPtr,short aLen,short bLen,Handle intlParam)
  44860.     = {0x3F3C,0x001A,0xA9ED}; 
  44861. æDT short myVariable = IUMagPString((Ptr) aPtr,(Ptr) bPtr,(short) aLen,(short) bLen,(Handle) intlParam);
  44862. æC 
  44863.  
  44864. æKY IUMagIDPString
  44865. æFc Packages.h
  44866. æT Function
  44867. æD pascal short IUMagIDPString(Ptr aPtr,Ptr bPtr,short aLen,short bLen,Handle intlParam)
  44868.     = {0x3F3C,0x001C,0xA9ED}; 
  44869. æDT short myVariable = IUMagIDPString((Ptr) aPtr,(Ptr) bPtr,(short) aLen,(short) bLen,(Handle) intlParam);
  44870. æC 
  44871.  
  44872. æKY IUCompPString
  44873. æFc Packages.h
  44874. æT Function
  44875. æD pascal short IUCompPString(const Str255 aStr,const Str255 bStr,Handle intlParam)
  44876.     = {0x241F,0x225F,0x205F,0x4240,0x4241,0x1018,0x1219,0x2F08,0x2F09,0x3F00,0x3F01,0x2F02,0x3F3C,0x001A,0xA9ED}; 
  44877. æDT short myVariable = IUCompPString((const Str255) aStr,(const Str255) bStr,(Handle) intlParam);
  44878. æC 
  44879.  
  44880. æKY IUEqualPString
  44881. æFc Packages.h
  44882. æT Function
  44883. æD pascal short IUEqualPString(const Str255 aStr,const Str255 bStr,Handle intlParam)
  44884.     = {0x241F,0x225F,0x205F,0x4240,0x4241,0x1018,0x1219,0x2F08,0x2F09,0x3F00,0x3F01,0x2F02,0x3F3C,0x001C,0xA9ED}; 
  44885. æDT short myVariable = IUEqualPString((const Str255) aStr,(const Str255) bStr,(Handle) intlParam);
  44886. æC 
  44887.  
  44888. æKY IUScriptOrder
  44889. æFc Packages.h
  44890. æT Function
  44891. æD pascal short IUScriptOrder(ScriptCode script1,ScriptCode script2)
  44892.     = {0x3F3C,0x001E,0xA9ED}; 
  44893. æDT short myVariable = IUScriptOrder((ScriptCode) script1,(ScriptCode) script2);
  44894. æC 
  44895.  
  44896. æKY IULangOrder
  44897. æFc Packages.h
  44898. æT Function
  44899. æD pascal short IULangOrder(LangCode language1,LangCode language2)
  44900.     = {0x3F3C,0x0020,0xA9ED}; 
  44901. æDT short myVariable = IULangOrder((LangCode) language1,(LangCode) language2);
  44902. æC 
  44903.  
  44904. æKY IUTextOrder
  44905. æFc Packages.h
  44906. æT Function
  44907. æD pascal short IUTextOrder(Ptr aPtr,Ptr bPtr,short aLen,short bLen,ScriptCode aScript,
  44908.     ScriptCode bScript,LangCode aLang,LangCode bLang)
  44909.     = {0x3F3C,0x0022,0xA9ED}; 
  44910. æDT short myVariable = IUTextOrder((Ptr) aPtr,(Ptr) bPtr,(short) aLen,(short) bLen,(ScriptCode) aScript,()
  44911.     ScriptCode bScript,(LangCode) aLang,(LangCode) bLang);
  44912. æC 
  44913.  
  44914. æKY IUStringOrder
  44915. æFc Packages.h
  44916. æT Function
  44917. æD pascal short IUStringOrder(const Str255 aStr,const Str255 bStr,ScriptCode aScript,
  44918.     ScriptCode bScript,LangCode aLang,LangCode bLang)
  44919.     = {0x240A,0x221F,0x201F,0x244F,0x594F,0x2F00,0x2F01,0x225A,0x205A,0x4240,0x4241,0x1018,0x1219,0x2508,0x2509,0x3500,0x3501,0x2442,0x3F3C,0x0022,0xA9ED}; 
  44920. æDT short myVariable = IUStringOrder((const Str255) aStr,(const Str255) bStr,(ScriptCode) aScript,()
  44921.     ScriptCode bScript,(LangCode) aLang,(LangCode) bLang);
  44922. æC 
  44923.  
  44924. æKY IUGetItlTable
  44925. æFc Packages.h
  44926. æT Function
  44927. æD pascal void IUGetItlTable(ScriptCode script,short tableCode,Handle *itlHandle,
  44928.     long *offset,long *length)
  44929.     = {0x3F3C,0x0024,0xA9ED}; 
  44930. æDT IUGetItlTable((ScriptCode) script,(short) tableCode,(Handle *) itlHandle,(
  44931.     long) * offset,(long *) length);
  44932. æC 
  44933.  
  44934.  
  44935. æKY Palettes.h
  44936. æKL ActivatePalette
  44937. AnimateEntry
  44938. AnimatePalette
  44939. CopyPalette
  44940. CTab2Palette
  44941. DisposePalette
  44942. GetEntryColor
  44943. GetEntryUsage
  44944. GetNewPalette
  44945. GetPalette
  44946. InitPalettes
  44947. NewPalette
  44948. NSetPalette
  44949. Palette2CTab
  44950. PmBackColor
  44951. PmForeColor
  44952. SetEntryColor
  44953. SetEntryUsage
  44954. SetPalette
  44955.  
  44956. ColorInfo
  44957. Palette
  44958. PaletteHandle
  44959. PalettePtr
  44960. pmAllUpdates
  44961. pmAnimated
  44962. pmBkUpdates
  44963. pmCourteous
  44964. pmExplicit
  44965. pmFgUpdates
  44966. pmNoUpdates
  44967. pmTolerant
  44968.  
  44969. æKY pmCourteous
  44970. æFc Palettes.h
  44971. æT #define
  44972. æD #define pmCourteous 0 /*Record use of color on each device touched.*/
  44973. æC 
  44974. »Color Usage
  44975.  
  44976. The Palette Manager uses one of four methods for selecting colors:
  44977.  
  44978.   •  Courteous colors have no special properties. For such colors, the Palette
  44979.      Manager relies upon Color QuickDraw to select appropriate pixel values.
  44980.      Colors with specified usages that can’t be satisfied by the Palette
  44981.      Manager will default to courteous colors. This occurs, for example, when
  44982.      drawing to a device with no color look-up table, such as a direct or fixed
  44983.      device. Courteous colors don’t change the color environment in any way.
  44984.   •  Tolerant colors cause a change in the color environment unless the fit to
  44985.      the best matching available color falls within a separately specified
  44986.      tolerance value.
  44987.   •  Animating colors are reserved by a palette and are unavailable to (and
  44988.      can’t be matched by) any other request for color.
  44989.   •  Explicit colors always generate the corresponding entry in the device’s
  44990.      color table.
  44991.  
  44992. These color types are specified when using Palette Manager routines by using the
  44993. following constants:
  44994.  
  44995. CONST { Usage constants }
  44996.  
  44997.       pmCourteous = $0000;
  44998.       pmDithered  = $0001; {reserved for future use}
  44999.       pmTolerant  = $0002;
  45000.       pmAnimated  = $0004;
  45001.       pmExplicit  = $0008;
  45002.  
  45003. When you specify colors for a palette within a 'pltt' resource, you will usually
  45004. assign the same usage value to each color in the palette. However, if for some reason
  45005. a particular color must be used differently than the other colors in the palette, it
  45006. can be assigned a different usage value, either within the resource file, or within
  45007. the application through use of the SetEntryUsage routine.
  45008.  
  45009. The sections that follow provide more information on these color types.
  45010.  
  45011. »Courteous Colors
  45012.  
  45013. Courteous colors are provided for two reasons.  First, they are a convenient placeholder.
  45014.  If your application uses only a small number of colors you can place each of them in
  45015. a palette, ordered according to your preference.  Suppose you have a palette resource
  45016. which consists of a set of eight colors, namely white, black, red, orange, yellow,
  45017. green, blue, and violet, in that order, each with a usage specified as courteous. 
  45018. Assuming further that the palette resource ID number matched that of a color window
  45019. (myColorWindow) you opened earlier, the following calls will paint a rectangle (myRect)
  45020. in yellow (palette entry 4, where white is 0):
  45021.  
  45022.   SetPort (myColorWindow);
  45023.   PmForeColor (4);
  45024.   PaintRect (myRect);
  45025.  
  45026. This is exactly analogous to the following sequence of calls made using Color Quickdraw
  45027. routines, where yellowRGB is of type ColorSpec:
  45028.  
  45029.   with yellowRGB do begin {done once during your initialization}
  45030.        red := $FFFF;
  45031.        green := $FFFF;
  45032.        blue := $0000
  45033.        end;
  45034.  
  45035.   SetPort (myColorWindow);
  45036.   RGBForeColor (yellowRGB);
  45037.   PaintRect (myRect);
  45038.  
  45039. The second reason for providing courteous colors is not immediately apparent.  It
  45040. involves how colors are selected for palettes which use animation.  The Palette
  45041. Manager has access to all palettes used by all windows throughout the system.  When
  45042. deciding which of a device’s colors to allocate for animation, it checks each window
  45043. currently drawn on that device to see which colors the windows are using.  It then
  45044. chooses the color which is least used and reserves that for animation.  In the first
  45045. example shown above, the Palette Manager would try to avoid the eight colors used in
  45046. your palette, even though they are just courteous colors.  In the second example it
  45047. would have no knowledge of your colors and might steal them unnecessarily, and when
  45048. your window is redrawn the selected colors might not be as close to the desired
  45049. colors as they previously were.  If you intend to use only a limited number of colors
  45050. it is therefore best to place them in the window’s palette so the Palette Manager
  45051. will know about them.
  45052.  
  45053. »Tolerant Colors
  45054.  
  45055. Tolerant colors allow you to change the current color environment according to your
  45056. needs.  When your window becomes the frontmost window on a device its palette and the
  45057. colors contained therein are given preference.  Each tolerant color is compared to
  45058. the best unique match available in the current color environment (for each device on
  45059. which the window is drawn).  When the difference between your color and the best
  45060. available match is greater than the tolerance you have specified the Palette Manager
  45061. will modify the color environment to provide an exact match to your color.
  45062.  
  45063. The tolerance value associated with each palette entry is compared to a measure of
  45064. the difference between two RGBColor values.  This difference is an approximation of
  45065. the distance between the two points as measured in a Cartesian coordinate system
  45066. where the axes are the unsigned red, green, and blue values.  The distance formula
  45067. used is shown below:
  45068.  
  45069.   Δ RGB = maximum of (abs(Red1–Red2), abs(Green1–Green2), abs(Blue1–Blue2))
  45070.  
  45071. A value of $5000 is generally sufficient to allow matching without updates in reasonably
  45072. well-balanced color environments. A tolerance value of $0000 means that only an exact
  45073. match is acceptable. Any value of $0xxx, other than $0000, is reserved, and should
  45074. not be used in applications.
  45075.  
  45076. If your palette requires more colors than are currently available the Palette Manager
  45077. will check to see if any other palette has reserved entries for animation.  If so it
  45078. will dereserve them and make them available for your palette.  If you ask for more
  45079. than are available on a device, the Palette Manager cannot honor your request. 
  45080. However, you can still call PmForeColor for such colors; as mentioned earlier, such
  45081. colors default to courteous colors. Color QuickDraw will still select the best color
  45082. available, which of course must match one of the colors elsewhere in your palette
  45083. since the Palette Manager will only run out of colors after it has given your palette
  45084. all that it has.  Two exceptions to this rule are noted below.  See the “Black,
  45085. White, and Palette Customization” section and the “Palette Prioritization” section
  45086. describing the interaction among colors of different usages in a single palette.
  45087.  
  45088. »Animating Colors
  45089.  
  45090. Animating colors allow you to reserve device indexes for color table animation.  Each
  45091. animating color is checked to see if it already has a reserved index for the target
  45092. device.  If it does not, the Palette Manager attempts to find a suitable index.  This
  45093. is done by checking all windows to see what colors they use, and which device indexes
  45094. match those colors.  The least frequently used indexes are then reserved for your
  45095. palette.  The reservation process is analogous to the Color Manager call ReserveEntry.
  45096.  The device index and its corresponding color value is removed from the matching
  45097. scheme used by Color Quickdraw; you cannot draw with it by calling RGBForeColor. 
  45098. However, when you call PmForeColor the Palette Manager will locate the reserved index
  45099. and configure your window’s port to draw with it.  On multiple devices this will
  45100. likely be a different index for each device, but this process will be invisible to
  45101. your application.
  45102.  
  45103. After reserving one or more device indexes for each animating entry it detects, the
  45104. Palette Manager will change the color environment to match the RGB values specified
  45105. in the palette.  To use an animating color you must first draw with it using PmForeColor
  45106. or PmBackColor.  To effect color table animation you can use either AnimateEntry (for
  45107. a single color) or AnimatePalette (for a contiguous set of colors).  These calls are
  45108. described in the section titled
  45109. “Palette Manager Routines”.
  45110.  
  45111. »Explicit Colors
  45112.  
  45113. Explicit colors are provided as a convenience for users who wish to use colors in
  45114. very special ways.  The RGB value in a palette is completely ignored if a color is an
  45115. explicit color.  Explicit colors cause no change in the color environment and are not
  45116. counted for purposes of animation.  Explicit colors always match the corresponding
  45117. device index.  A PmForeColor call with a parameter of 12 will place a value of (12
  45118. modulo (MaxIndex+1)) into the foreground color field of your window’s cGrafPort,
  45119. where MaxIndex is the maximum available index for each device under consideration. 
  45120. When you draw with an explicit color, you get whatever color the device index currently
  45121. contains.
  45122.  
  45123. One interesting use for explicit colors is that it allows you to monitor the color
  45124. environment on a device.  For example, you could draw a grid of 256 explicit colors,
  45125. 16-by-16, in a small window.  The colors shown are exactly those in the device’s
  45126. color table.  If color table animation is taking place simultaneously the corresponding
  45127. colors in the small window will animate as well. If you display such a window on a
  45128. 4-bit device, the first 16 colors will match the 16 colors available in the device
  45129. and each row thereafter will be a copy of the first row.
  45130.  
  45131. However, the main purpose for explicit colors is to provide a convenient indexed
  45132. color interface.  Using the Color Manager, you can establish a known color environment
  45133. using the SetEntries routine on each device of interest.  You can then easily select
  45134. any of these colors for drawing by setting your window’s palette to contain as many
  45135. explicit colors as are in the target device with the greatest number of indexes. 
  45136. PmForeColor will configure the cGrafPort to draw with the index of your choice.
  45137.  
  45138. Warning:  You should not use explicit colors in this fashion if you intend
  45139.           your application to coexist in multi-application environments such
  45140.           as those provided by MultiFinder™ or A/UX™ or when using color desk
  45141.           accessories that depend upon the Palette Manager.  However, for
  45142.           certain types of applications, especially those which are written
  45143.           for a known device environment, explicit colors will tend to make
  45144.           indexed color manipulation much more convenient.
  45145.  
  45146. æKY pmTolerant
  45147. æFc Palettes.h
  45148. æT #define
  45149. æD #define pmTolerant 2 /*render ciRGB if ciTolerance is exceeded by best match.*/
  45150. æC 
  45151.  
  45152. æKY pmAnimated
  45153. æFc Palettes.h
  45154. æT #define
  45155. æD #define pmAnimated 4 /*reserve an index on each device touched and render ciRGB.*/
  45156. æC 
  45157.  
  45158. æKY pmExplicit
  45159. æFc Palettes.h
  45160. æT #define
  45161. æD #define pmExplicit 8 /*no reserve, no render, no record; stuff index into port.*/
  45162. æC 
  45163.  
  45164. æKY pmNoUpdates
  45165. æFc Palettes.h
  45166. æT #define
  45167. æD 
  45168. /* NSetPalette Update Constants */
  45169.  
  45170. #define pmNoUpdates 0x8000 /*no updates*/
  45171. æC 
  45172.  
  45173. æKY pmBkUpdates
  45174. æFc Palettes.h
  45175. æT #define
  45176. æD #define pmBkUpdates 0xA000 /*background updates only*/
  45177. æC 
  45178.  
  45179. æKY pmFgUpdates
  45180. æFc Palettes.h
  45181. æT #define
  45182. æD #define pmFgUpdates 0xC000 /*foreground updates only*/
  45183. æC 
  45184.  
  45185. æKY pmAllUpdates
  45186. æFc Palettes.h
  45187. æT #define
  45188. æD #define pmAllUpdates 0xE000 /*all updates*/
  45189. æC 
  45190.  
  45191. æKY ColorInfo
  45192. æFc Palettes.h
  45193. æT struct
  45194. æD struct ColorInfo {
  45195.     RGBColor ciRGB; /*true RGB values*/
  45196.     short ciUsage; /*color usage*/
  45197.     short ciTolerance; /*tolerance value*/
  45198.     short ciDataFields[3]; /*private fields*/
  45199. };
  45200.  
  45201. typedef struct ColorInfo ColorInfo;
  45202. æC 
  45203. »COLOR PALETTE RECORDS
  45204. _______________________________________________________________________________
  45205.  
  45206. The basic data structure for a color palette is the ColorInfo record. It consists of
  45207. the following:
  45208.  
  45209. TYPE
  45210.  ColorInfo = RECORD
  45211.                ciRGB:        RGBColor;  {absolute RGB values}
  45212.                ciUsage:      INTEGER    {color usage information}
  45213.                ciTolerance:  INTEGER;   {tolerance value}
  45214.                ciFlags:      INTEGER;   {private field}
  45215.                ciPrivate:    LONGINT;   {private field}
  45216.              END;
  45217.  
  45218. Field descriptions
  45219.  
  45220. ciRGB        The ciRGB is the absolute RGB value defined by Color QuickDraw.
  45221. ciUsage      The ciUsage field contains color usage information that
  45222.              determines the properties of a color.
  45223. ciTolerance  The ciTolerance is a value used to determine if a color is close
  45224.              enough to the color chosen; if the tolerance value is exceeded,
  45225.              the preferred color is rendered in the device’s color table for
  45226.              the selected index.
  45227. ciFlags      The ciFlags field is used internally by the Palette Manager.
  45228. ciPrivate    The ciPrivate field is used internally to store information
  45229.              about color allocation: not for use by application.
  45230.  
  45231. The data structure for a color palette is made up of an array of ColorInfo records,
  45232. plus other information relating to the use of the colors within the palette. The
  45233. 'pltt' resource is an image of the Palette data structure.
  45234.  
  45235. Note:  The palette is accessed through the Palette Manager routines only:
  45236.        do not attempt to directly access any of the fields in this data
  45237.        structure.
  45238.  
  45239. æKY Palette
  45240. PalettePtr
  45241. PaletteHandle
  45242. æFc Palettes.h
  45243. æT struct
  45244. æD struct Palette {
  45245.     short pmEntries; /*entries in pmTable*/
  45246.     short pmDataFields[7]; /*private fields*/
  45247.     ColorInfo pmInfo[1];
  45248. };
  45249.  
  45250. typedef struct Palette Palette;
  45251. typedef Palette *PalettePtr, **PaletteHandle;
  45252.  
  45253. æC 
  45254. TYPE
  45255.    PaletteHandle = ^PalettePtr;
  45256.    PalettePtr    = ^Palette;
  45257.    Palette       = RECORD
  45258.                      pmEntries:     integer;                 {entries in pmInfo}
  45259.                      pmDataFields:  array [0..6] of integer; {private fields}
  45260.                      pmInfo:        array [0..0] of ColorInfo;
  45261.                    END;
  45262.  
  45263. Field descriptions
  45264.  
  45265. pmEntries     The pmEntries field contains the number of entries in the pmTable.
  45266. pmDataFields  The pmDataFields field contains an array of integers that are
  45267.               used internally by the Palette Manager.
  45268. pmInfo        The pmInfo field contains an array of ColorInfo records.
  45269.  
  45270. æKY InitPalettes
  45271. æFc Palettes.h
  45272. æT Function
  45273. æTN AA90
  45274. æD pascal void InitPalettes(void)
  45275.     = 0xAA90; 
  45276. æDT InitPalettes()(void);
  45277. æMM
  45278. æRT 211
  45279. æRI V-161, VI
  45280. æC 
  45281. InitPalettes initializes the Palette Manager. It searches for devices which
  45282. support a Color Look-Up Table (CLUT) and initializes an internal data structure
  45283. for each one. This procedure is called by InitWindows and should not have to be
  45284. issued by your application. 
  45285.  
  45286. æKY NewPalette
  45287. æFc Palettes.h
  45288. æT Function
  45289. æTN AA91
  45290. æD pascal PaletteHandle NewPalette(short entries,CTabHandle srcColors,short srcUsage,
  45291.     short srcTolerance)
  45292.     = 0xAA91; 
  45293. æDT PaletteHandle myVariable = NewPalette((short) entries,(CTabHandle) srcColors,(short) srcUsage,()
  45294.     short srcTolerance);
  45295. æMM
  45296. æRI V-161, VI
  45297. æC 
  45298. NewPalette allocates a new palette containing a table of colors with enough room
  45299. for the number of colors specified by the entries parameter. NewPalette fills
  45300. the table with as many RGB values from the color table named by the srcColors
  45301. parameter as it has or as it can fit. NewPalette sets the usage field of each
  45302. color to the value in the srcUsage parameter and the tolerance value of each
  45303. color to the value in the srcTolerance parameter. If no color table is provided 
  45304. (srcColors = NIL) then all colors in the palette are set to black (red, green,
  45305. and blue equal to $0000 ). 
  45306.  
  45307. æKY GetNewPalette
  45308. æFc Palettes.h
  45309. æT Function
  45310. æTN AA92
  45311. æD pascal PaletteHandle GetNewPalette(short PaletteID)
  45312.     = 0xAA92; 
  45313. æDT PaletteHandle myVariable = GetNewPalette((short) PaletteID);
  45314. æMM
  45315. æRI V-162,VI
  45316. æC 
  45317. GetNewPalette creates a palette from information supplied by the Resource
  45318. Manager, initializes it, and attaches the palette to the current window. If you
  45319. open a new color window with GetNewCWindow, this routine is called automatically
  45320. with paletteID equal to the window’s resource ID. A palette resource is
  45321. identified by type 'pltt'. A paletteID of 0 is reserved for the application
  45322. palette resource, which is used as the default palette for noncolor windows and
  45323. color windows without assigned palettes. If there is no assigned palette or
  45324. application default palette, GetNewPalette uses the system palette with resource
  45325. ID 0. 
  45326.  
  45327. æKY DisposePalette
  45328. æFc Palettes.h
  45329. æT Function
  45330. æTN AA93
  45331. æD pascal void DisposePalette(PaletteHandle srcPalette)
  45332.     = 0xAA93; 
  45333. æDT DisposePalette((PaletteHandle) srcPalette);
  45334. æMM
  45335. æRI V-162, VI
  45336. æC 
  45337. DisposePalette disposes of a Palette. If the palette has any entries allocated
  45338. for animation on any display device, these entries are relinquished prior to
  45339. deallocation of the palette. 
  45340.  
  45341. æKY ActivatePalette
  45342. æFc Palettes.h
  45343. æT Function
  45344. æTN AA94
  45345. æD pascal void ActivatePalette(WindowPtr srcWindow)
  45346.     = 0xAA94; 
  45347. æDT ActivatePalette((WindowPtr) srcWindow);
  45348. æMM
  45349. æRI V-162, VI
  45350. æC 
  45351. ActivatePalette is called by the Window Manager when your window’s status
  45352. changes: for example, when your window opens, closes, moves, or becomes
  45353. frontmost. You should call ActivatePalette after making changes to a palette
  45354. with Palette Manager routines such as SetEntryColor. Such changes do not take
  45355. effect until the next call to ActivatePalette, thereby allowing you to make a
  45356. series of palette changes without any immediate change in the color environment.
  45357.  
  45358. If the window specifed in the srcWindow parameter is frontmost, ActivatePalette
  45359. examines the information stored in the palette associated with the window and
  45360. attempts to provide the color environment described therein. It determines a
  45361. list of devices on which to render the palette by intersecting the port
  45362. rectangle of the window with each device. If the intersection is not empty, and
  45363. if the device has a Color Look-Up Table (CLUT), then ActivatePalette checks to
  45364. see if the color environment is sufficient. If a change is required,
  45365. ActivatePalette calls the Color Manager to reserve or modify the device’s color
  45366. entries as required. It then generates update events for all affected windows
  45367. which need color updates.
  45368.  
  45369. Calling ActivatePalette with an off-screen port has no effect.
  45370.  
  45371. æKY SetPalette
  45372. æFc Palettes.h
  45373. æT Function
  45374. æTN AA95
  45375. æD pascal void SetPalette(WindowPtr dstWindow,PaletteHandle srcPalette,Boolean cUpdates)
  45376.     = 0xAA95; 
  45377. æDT SetPalette((WindowPtr) dstWindow,(PaletteHandle) srcPalette,(Boolean) cUpdates);
  45378. æRT 211
  45379. æRI V-162, VI
  45380. æC 
  45381. SetPalette changes the palette associated with the window specified by the
  45382. dstWindow parameter to the palette specified by the srcPalette parameter. It
  45383. also records whether the window wants to receive updates as a result of a change
  45384. to its color environment. If you want dstWindow to be updated whenever its color
  45385. environment changes, set the cUpdates parameter to TRUE. 
  45386.  
  45387. æKY NSetPalette
  45388. æFc Palettes.h
  45389. æT Function
  45390. æTN AA95
  45391. æD pascal void NSetPalette(WindowPtr dstWindow,PaletteHandle srcPalette,short nCUpdates)
  45392.     = 0xAA95; 
  45393. æDT NSetPalette((WindowPtr) dstWindow,(PaletteHandle) srcPalette,(short) nCUpdates);
  45394. æRT 211
  45395. æC 
  45396. NSetPalette is identical to SetPalette except that the nCUpdates parameter is an
  45397. Integer rather than a Boolean. NSetPalette changes the palette associated with
  45398. the windwo specified by the dstWindow parameter to srcPalette. NSetPalette also
  45399. records whether the window wants to receive updates as a result of a change to
  45400. its color environment. If you want the window to be updated whenever its color
  45401. environment changes, set nCUpdates to the constant pmAllUpdates. If you are only
  45402. interested in updates when the window is the active window, set nCUpdates to the
  45403. constant pmFgUpdates. If you are only interested in updates when dstWindow is
  45404. not the active window, set nCUpdates to the constant pmBkUpdates.
  45405.  
  45406. { NSetPalette Update Constants }
  45407. pmNoUpdates   = $8000;  {no updates}
  45408. pmBkUpdates   = $A000;  {background updates only}
  45409. pmFgUpdates   = $C000;  {foreground updates only}
  45410. pmAllUpdates  = $E000;  {all updates}
  45411.  
  45412. NSetPalette is available in System software version 6.0.2 and later.  
  45413.  
  45414. æKY GetPalette
  45415. æFc Palettes.h
  45416. æT Function
  45417. æTN AA96
  45418. æD pascal PaletteHandle GetPalette(WindowPtr srcWindow)
  45419.     = 0xAA96; 
  45420. æDT PaletteHandle myVariable = GetPalette((WindowPtr) srcWindow);
  45421. æRT 211
  45422. æRI V-163, VI
  45423. æC 
  45424. GetPalette returns a handle to the palette associated with the window specified
  45425. by the srcWindow parameter. If there is no associated palette, or if the window
  45426. is not a color window, GetPalette returns NIL.
  45427.  
  45428. æKY CopyPalette
  45429. æFc Palettes.h
  45430. æT Function
  45431. æTN AAA1
  45432. æD pascal void CopyPalette(PaletteHandle srcPalette,PaletteHandle dstPalette,
  45433.     short srcEntry,short dstEntry,short dstLength)
  45434.     = 0xAAA1; 
  45435. æDT CopyPalette((PaletteHandle) srcPalette,(PaletteHandle) dstPalette,()
  45436.     short srcEntry,(short) dstEntry,(short) dstLength);
  45437. æMM
  45438. æRT 211
  45439. æC 
  45440. CopyPalette copies entries from the source palette into the destination palette;
  45441. the copy begins at the values specified by the srcEntry and dstEntry parameters,
  45442. respectively, copying into as many entries as are specified by the dstLength
  45443. parameter. CopyPalette will resize the destination palette when the number of
  45444. entries after the copy is greater than the original.
  45445.  
  45446. CopyPalette does not call ActivatePalette, so your application is free to do a
  45447. number of palette changes without causing a series of intermediate changes to
  45448. the color environment; your application should call ActivatePalette after
  45449. completing all palette changes.
  45450.  
  45451. If either of the palette handles are NIL, CopyPalette does nothing.
  45452.  
  45453. æKY PmForeColor
  45454. æFc Palettes.h
  45455. æT Function
  45456. æTN AA97
  45457. æD pascal void PmForeColor(short dstEntry)
  45458.     = 0xAA97; 
  45459. æDT PmForeColor((short) dstEntry);
  45460. æMM
  45461. æRT 211
  45462. æRI V-163, VI
  45463. æC 
  45464. PmForeColor sets the RGB and index forecolor fields of the current cGrafPort to
  45465. match the palette entry of the current cGrafPort (window) corresponding to the
  45466. value in the dstEntry parameter.  
  45467.  
  45468. For courteous and tolerant entries, PmForeColor calls the RGBForeColor routine
  45469. using the RGB color of the palette entry. For animating colors PmForeColor
  45470. selects the recorded device index previously reserved for animation (if still
  45471. present) and installs it in the cGrafPort. The RGB forecolor field is set to the
  45472. value from the palette entry. For explicit colors PmForeColor places (dstEntry
  45473. modulo (MaxIndex+1)) into the cGrafPort, where MaxIndex is the largest index
  45474. available in a device’s CLUT. 
  45475.  
  45476. When multiple devices are present with different depths, MaxIndex varies
  45477. appropriately for each device. 
  45478.  
  45479. æKY PmBackColor
  45480. æFc Palettes.h
  45481. æT Function
  45482. æTN AA98
  45483. æD pascal void PmBackColor(short dstEntry)
  45484.     = 0xAA98; 
  45485. æDT PmBackColor((short) dstEntry);
  45486. æMM
  45487. æRT 211
  45488. æRI V-163, VI
  45489. æC 
  45490. PmBackColor sets the RGB and index backcolor fields of the current cGrafPort to
  45491. match the palette entry of the current cGrafPort (window) corresponding to the
  45492. value in the dstEntry parameter. 
  45493.  
  45494. For courteous and tolerant entries, PmBackColor calls the RGBBackColor routine
  45495. using the RGB color of the palette entry. For animating colors it will select
  45496. the recorded device index previously reserved for animation (if still present)
  45497. and install it in the cGrafPort. The RGB backcolor field is set to the value
  45498. from the palette entry. For explicit colors PmBackColor places (dstEntry modulo 
  45499. (MaxIndex+1)) into the cGrafPort, where MaxIndex is the largest index available
  45500. in a device’s color table. 
  45501.  
  45502. When multiple devices are present with different depths, MaxIndex varies
  45503. appropriately for each device. 
  45504.  
  45505. æKY AnimateEntry
  45506. æFc Palettes.h
  45507. æT Function
  45508. æTN AA99
  45509. æD pascal void AnimateEntry(WindowPtr dstWindow,short dstEntry,const RGBColor *srcRGB)
  45510.     = 0xAA99; 
  45511. æDT AnimateEntry((WindowPtr) dstWindow,(short) dstEntry,(const RGBColor *) srcRGB);
  45512. æRI V-164, VI
  45513. æC 
  45514. AnimateEntry changes the RGB value of a palette entry of a window. The palette
  45515. entry is specified by the dstEntry parameter; the window is specified by the
  45516. dstWindow parameter. Each device for which an index has been reserved is
  45517. immediately modified to contain the new value. This is not considered to be a
  45518. change to the device’s color environment since no other windows should be using
  45519. the animated entry. 
  45520.  
  45521. If the palette entry is not an animating color, or if the associated indexes are
  45522. no longer reserved, no animation is performed. 
  45523.  
  45524. If you have blocked color updates in a window by using SetPalette with CUpdates
  45525. set to FALSE, you may observe undesired animation. This occurs when
  45526. ActivatePalette reserves device indexes for animation that are already used in
  45527. the window. Redrawing the window, which normally occurs as the result of a color
  45528. update event, removes any animating colors that do not belong to it.
  45529.  
  45530. æKY AnimatePalette
  45531. æFc Palettes.h
  45532. æT Function
  45533. æTN AA9A
  45534. æD pascal void AnimatePalette(WindowPtr dstWindow,CTabHandle srcCTab,short srcIndex,
  45535.     short dstEntry,short dstLength)
  45536.     = 0xAA9A; 
  45537. æDT AnimatePalette((WindowPtr) dstWindow,(CTabHandle) srcCTab,(short) srcIndex,()
  45538.     short dstEntry,(short) dstLength);
  45539. æRI V-164, VI
  45540. æC 
  45541. The AnimatePalette procedure performs a function similar to AnimateEntry, but it
  45542. acts upon a range of palette entries. Beginning at the index specified by the
  45543. srcIndex parameter (which has a minimum value of 0), the next dstLength entries
  45544. are copied from the source color table to the destination window’s palette,
  45545. beginning at the entry specified by the dstEntry parameter. If the source color
  45546. table is not sufficiently large to accommodate the request, as many entries are
  45547. modified as possible and the remaining entries are left unchanged. 
  45548.  
  45549. æKY GetEntryColor
  45550. æFc Palettes.h
  45551. æT Function
  45552. æTN AA9B
  45553. æD pascal void GetEntryColor(PaletteHandle srcPalette,short srcEntry,RGBColor *dstRGB)
  45554.     = 0xAA9B; 
  45555. æDT GetEntryColor((PaletteHandle) srcPalette,(short) srcEntry,(RGBColor *) dstRGB);
  45556. æRI V-164, VI
  45557. æC 
  45558. GetEntryColor allows your application to access the color of a palette entry.
  45559. The RGB color found in the entry specified by the srcEntry parameter is stored
  45560. in the destination RGBColor record. The color may be modified by using the
  45561. SetEntryColor routine. 
  45562.  
  45563. æKY SetEntryColor
  45564. æFc Palettes.h
  45565. æT Function
  45566. æTN AA9C
  45567. æD pascal void SetEntryColor(PaletteHandle dstPalette,short dstEntry,const RGBColor *srcRGB)
  45568.     = 0xAA9C; 
  45569. æDT SetEntryColor((PaletteHandle) dstPalette,(short) dstEntry,(const RGBColor *) srcRGB);
  45570. æRI V-165, VI
  45571. æC 
  45572. SetEntryColor provides a convenient way for your application to modify the color
  45573. of a single palette entry. The RGB color of the srcRGB parameter is stored in
  45574. the palette entry specified by the dstEntry parameter. When you use
  45575. SetEntryColor, the entry is marked as having changed, but no change occurs in
  45576. the color environment. The change will be effected upon the next call to
  45577. ActivatePalette. Modified entries are marked such that the palette will be
  45578. updated even though no update might be required by a change in the color
  45579. environment. 
  45580.  
  45581. æKY GetEntryUsage
  45582. æFc Palettes.h
  45583. æT Function
  45584. æTN AA9D
  45585. æD pascal void GetEntryUsage(PaletteHandle srcPalette,short srcEntry,short *dstUsage,
  45586.     short *dstTolerance)
  45587.     = 0xAA9D; 
  45588. æDT GetEntryUsage((PaletteHandle) srcPalette,(short) srcEntry,(short *) dstUsage,(
  45589.     short) * dstTolerance);
  45590. æRI V-165, VI
  45591. æC 
  45592. GetEntryUsage allows your application to access the usage and tolerance fields
  45593. of a palette entry. The usage and tolerance values found in the entry specified
  45594. by the srcEntry parameter are stored in the destination usage and tolerance
  45595. integers. These fields may be modified by using the SetEntryUsage routine. 
  45596.  
  45597. æKY SetEntryUsage
  45598. æFc Palettes.h
  45599. æT Function
  45600. æTN AA9E
  45601. æD pascal void SetEntryUsage(PaletteHandle dstPalette,short dstEntry,short srcUsage,
  45602.     short srcTolerance)
  45603.     = 0xAA9E; 
  45604. æDT SetEntryUsage((PaletteHandle) dstPalette,(short) dstEntry,(short) srcUsage,()
  45605.     short srcTolerance);
  45606. æRI V-165, VI
  45607. æC 
  45608. SetEntryUsage provides a convenient way for your application to modify the usage
  45609. of a single palette entry. The usage and tolerance values specified by the
  45610. srcUsage and srcTolerance parameters are stored in the palette entry specified
  45611. by the dstEntry parameter. When you use SetEntryUsage, the entry is marked as
  45612. having changed, but no change occurs in the color environment. The change will
  45613. be effected upon the next call to ActivatePalette. Modified entries are marked
  45614. such that the palette will be updated even though no update might be required by
  45615. a change in the color environment. If either srcUsage or srcTolerance are set to
  45616. $FFFF (–1) they will not be changed. 
  45617.   
  45618. This procedure is provided to allow easy modifications to a palette created with
  45619. NewPalette or modified by CTab2Palette. In such cases the ciUsage and
  45620. ciTolerance fields are homogeneous since only one value can be designated for
  45621. each. You will typically call SetEntryUsage after those calls in order to adjust
  45622. and customize your palette. 
  45623.  
  45624. æKY CTab2Palette
  45625. æFc Palettes.h
  45626. æT Function
  45627. æTN AA9F
  45628. æD pascal void CTab2Palette(CTabHandle srcCTab,PaletteHandle dstPalette,short srcUsage,
  45629.     short srcTolerance)
  45630.     = 0xAA9F; 
  45631. æDT CTab2Palette((CTabHandle) srcCTab,(PaletteHandle) dstPalette,(short) srcUsage,()
  45632.     short srcTolerance);
  45633. æMM
  45634. æRI V-165, VI
  45635. æC 
  45636. CTab2Palette is a convenience procedure that copies the fields from an existing
  45637. ColorTable record into an existing Palette record. If the records are not the
  45638. same size then the Palette record is resized to match the number of entries in
  45639. the ColorTable record. If dstPalette has any entries allocated for animation on
  45640. any display device, they are relinquished prior to copying the new colors. 
  45641.  
  45642. If you wish to effect color table animation you can change the colors in a
  45643. palette, and on corresponding devices, with the AnimateEntry and AnimatePalette
  45644. routines. Changes made to a palette by CTab2Palette don’t take effect until the
  45645. next ActivatePalette is performed. If either the color table handle or the
  45646. palette handle are NIL, no operation is performed. 
  45647.  
  45648. æKY Palette2CTab
  45649. æFc Palettes.h
  45650. æT Function
  45651. æTN AAA0
  45652. æD pascal void Palette2CTab(PaletteHandle srcPalette,CTabHandle dstCTab)
  45653.     = 0xAAA0; 
  45654. æDT Palette2CTab((PaletteHandle) srcPalette,(CTabHandle) dstCTab);
  45655. æMM
  45656. æRI V-166, VI
  45657. æC 
  45658. Palette2CTab is a convenience procedure which copies all of the colors from an
  45659. existing Palette record into an existing ColorTable record. If the records are
  45660. not the same size then the ColorTable record is resized to match the number of
  45661. entries in the Palette record. If either the palette handle or the color table
  45662. handle are NIL, no operation is performed. 
  45663.  
  45664.  
  45665. æKY Perf.h
  45666. æKL InitPerf
  45667. PerfControl
  45668. PerfDump
  45669. TermPerf
  45670.  
  45671. TP2PerfGlobals
  45672. TPerfGlobals
  45673.  
  45674. æKY TPerfGlobals
  45675. TP2PerfGlobals
  45676. æFc Perf.h
  45677. æT struct
  45678. æD struct TPerfGlobals {
  45679.     long startROM; /*ROM Base*/
  45680.     long romHits; /*used if MeasureROM is false*/
  45681.     long misses; /*count of PC values outside measured memory*/
  45682.     long (*segArray)[1]; /*array of segment handles*/
  45683.     long (*sizeArray)[1]; /*array of segment sizes*/
  45684.     short (**idArray)[1]; /*array of segment rsrc IDs*/
  45685.     long (*baseArray)[1]; /*array of offsets to counters for each segment*/
  45686.     long (*samples)[1]; /*samples buffer*/
  45687.     long buffSize; /*size of samples buffer in bytes*/
  45688.     short timeInterval; /*number of clock intervals between interrupts*/
  45689.     short bucketSize; /*size of buckets power of 2*/
  45690.     short log2buckSize; /*used in CvtPC*/
  45691.     short pcOffset; /*offset to the user PC at interrupt time.*/
  45692.     short numMeasure; /*# Code segments (w/o jump table)- ROM etc.*/
  45693.     short firstCode; /*index of first Code segment*/
  45694.     Boolean takingSamples; /*true if sampling is enabled.*/
  45695.     Boolean measureROM;
  45696.     Boolean measureCode;
  45697.     short ramSeg; /*index of "segment" record to cover RAM > 0 if RAM (misses) are to be bucketed.*/
  45698.     long ramBase; /*beginning of RAM being measured.*/
  45699.     short measureRAMbucketSize;
  45700.     short measureRAMlog2buckSize;
  45701.     short romVersion;
  45702.     short vRefNum; /*Volume where the report file is to be created*/
  45703.     Boolean volumeSelected; /*True if user selects the report file name*/
  45704.     Str255 rptFileName; /*Report file name*/
  45705.     Str255 rptFileCreator; /*Report File Creator*/
  45706.     Str255 rptFileType; /*Report File type*/
  45707.     ResType getResType; /*Resource type*/
  45708. };
  45709.  
  45710. typedef struct TPerfGlobals TPerfGlobals;
  45711. typedef TPerfGlobals *TP2PerfGlobals;
  45712.  
  45713. /* PerfGlobals are declared as a record, so main program can allocate
  45714. as globals, desk accessory can add to globals allocated via pointer,
  45715. print driver can allocate via low memory, etc. */
  45716.  
  45717.  
  45718.  
  45719. æC 
  45720.  
  45721. æKY InitPerf
  45722. æFc Perf.h
  45723. æT Function
  45724. æD pascal Boolean InitPerf(TP2PerfGlobals *thePerfGlobals,short timerCount,
  45725.     short codeAndROMBucketSize,Boolean doROM,Boolean doAppCode,const Str255 appCodeType,
  45726.     short romID,const Str255 romName,Boolean doRAM,long ramLow,long ramHigh,
  45727.     short ramBucketSize); 
  45728. æDT Boolean myVariable = InitPerf((TP2PerfGlobals *) thePerfGlobals,(short) timerCount,()
  45729.     short codeAndROMBucketSize,(Boolean) doROM,(Boolean) doAppCode,(const Str255) appCodeType,()
  45730.     short romID,(const Str255) romName,(Boolean) doRAM,(long) ramLow,(long) ramHigh,()
  45731.     short ramBucketSize);
  45732. æC 
  45733. called once to setup Performance monitoring
  45734.  
  45735. æKY TermPerf
  45736. æFc Perf.h
  45737. æT Function
  45738. æD pascal void TermPerf(TP2PerfGlobals thePerfGlobals); 
  45739. æDT TermPerf((TP2PerfGlobals) thePerfGlobals);
  45740. æC 
  45741. if InitPerf succeeds then TermPerf must be called before terminating program.
  45742.  
  45743. æKY PerfControl
  45744. æFc Perf.h
  45745. æT Function
  45746. æD pascal Boolean PerfControl(TP2PerfGlobals thePerfGlobals,Boolean turnOn); 
  45747. æDT Boolean myVariable = PerfControl((TP2PerfGlobals) thePerfGlobals,(Boolean) turnOn);
  45748. æC  
  45749. Call this to turn off/on measuring.
  45750.      Returns previous state.
  45751.  
  45752. æKY PerfDump
  45753. æFc Perf.h
  45754. æT Function
  45755. æD pascal short PerfDump(TP2PerfGlobals thePerfGlobals,const Str255 reportFile,
  45756.     Boolean doHistogram,short rptFileColumns); 
  45757. æDT short myVariable = PerfDump((TP2PerfGlobals) thePerfGlobals,(const Str255) reportFile,()
  45758.     Boolean doHistogram,(short) rptFileColumns);
  45759. æC 
  45760. Call this to dump the statistics into a file.
  45761.  
  45762.  
  45763. æKY Picker.h
  45764. æKL CMY2RGB
  45765. Fix2SmallFract
  45766. GetColor
  45767. HSL2RGB
  45768. HSV2RGB
  45769. RGB2CMY
  45770. RGB2HSL
  45771. RGB2HSV
  45772. SmallFract2Fix
  45773.  
  45774. CMYColor
  45775. HSLColor
  45776. HSVColor
  45777. MaxSmallFract
  45778. SmallFract
  45779.  
  45780. æKY MaxSmallFract
  45781. æFc Picker.h
  45782. æT #define
  45783. æD #define MaxSmallFract 0x0000FFFF /*Maximum small fract value, as long*/
  45784. æC 
  45785.  
  45786. æKY SmallFract
  45787. æFc Picker.h
  45788. æT typedef
  45789. æD 
  45790. /* A SmallFract value is just the fractional part of a Fixed number,
  45791. which is the low order word.  SmallFracts are used to save room,
  45792. and to be compatible with Quickdraw's RGBColor.  They can be
  45793. assigned directly to and from INTEGERs. */
  45794.  
  45795. typedef unsigned short SmallFract; /* Unsigned fraction between 0 and 1 */
  45796.  
  45797. /* For developmental simplicity in switching between the HLS and HSV
  45798. models, HLS is reordered into HSL.  Thus both models start with
  45799. hue and saturation values; value/lightness/brightness is last. */
  45800.  
  45801. æC 
  45802.  
  45803. æKY HSVColor
  45804. æFc Picker.h
  45805. æT struct
  45806. æD struct HSVColor {
  45807.     SmallFract hue; /*Fraction of circle, red at 0*/
  45808.     SmallFract saturation; /*0-1, 0 for gray, 1 for pure color*/
  45809.     SmallFract value; /*0-1, 0 for black, 1 for max intensity*/
  45810. };
  45811.  
  45812. typedef struct HSVColor HSVColor;
  45813. /* For developmental simplicity in switching between the HLS and HSVmodels, HLS
  45814.  is reordered into HSL.  Thus both models start with hue and saturation values;
  45815.  value/lightness/brightness is last. */
  45816. æC 
  45817.  
  45818. æKY HSLColor
  45819. æFc Picker.h
  45820. æT struct
  45821. æD struct HSLColor {
  45822.     SmallFract hue; /*Fraction of circle, red at 0*/
  45823.     SmallFract saturation; /*0-1, 0 for gray, 1 for pure color*/
  45824.     SmallFract lightness; /*0-1, 0 for black, 1 for white*/
  45825. };
  45826.  
  45827. typedef struct HSLColor HSLColor;
  45828. æC 
  45829.  
  45830. æKY CMYColor
  45831. æFc Picker.h
  45832. æT struct
  45833. æD struct CMYColor {
  45834.     SmallFract cyan;
  45835.     SmallFract magenta;
  45836.     SmallFract yellow;
  45837. };
  45838.  
  45839. typedef struct CMYColor CMYColor;
  45840. æC 
  45841.  
  45842. æKY Fix2SmallFract
  45843. æFc Picker.h
  45844. æT Function
  45845. æTN A82E
  45846. æD pascal SmallFract Fix2SmallFract(Fixed f)
  45847.     = {0x3F3C,0x0001,0xA82E}; 
  45848. æDT SmallFract myVariable = Fix2SmallFract((Fixed) f);
  45849. æMM
  45850. æRI VI
  45851. æC 
  45852. A SmallFract value can represent a value between 0 and 65,535. They can be
  45853. assigned directly to and from Integers.
  45854.   
  45855. The SmallFract2Fix function converts a SmallFract value to a fixed integer. 
  45856.  
  45857. The Fix2SmallFract function converts a fixed integer to a SmallFract value. 
  45858.  
  45859. æKY SmallFract2Fix
  45860. æFc Picker.h
  45861. æT Function
  45862. æTN A82E
  45863. æD pascal Fixed SmallFract2Fix(SmallFract s)
  45864.     = {0x3F3C,0x0002,0xA82E}; 
  45865. æDT Fixed myVariable = SmallFract2Fix((SmallFract) s);
  45866. æMM
  45867. æRI VI
  45868. æC 
  45869. A SmallFract value can represent a value between 0 and 65,535. They can be
  45870. assigned directly to and from Integers.
  45871.   
  45872. The SmallFract2Fix function converts a SmallFract value to a fixed integer. 
  45873.  
  45874. The Fix2SmallFract function converts a fixed integer to a SmallFract value. 
  45875.  
  45876. æKY CMY2RGB
  45877. æFc Picker.h
  45878. æT Function
  45879. æTN A82E
  45880. æD pascal void CMY2RGB(const CMYColor *cColor,RGBColor *rColor)
  45881.     = {0x3F3C,0x0003,0xA82E}; 
  45882. æDT CMY2RGB((const CMYColor *) cColor,(RGBColor *) rColor);
  45883. æMM
  45884. æC 
  45885. These six routines offer conversions between RGB on the one hand and CMY, HSV,
  45886. or HSL on the other.
  45887.  
  45888. PROCEDURE  CMY2RGB (cColor: CMYColor; VAR rColor: RGBColor);
  45889.  
  45890. The CMY2RGB procedure converts a CMYColor record to an RGBColor record.
  45891.  
  45892. PROCEDURE  HSL2RGB (hColor: HSLColor; VAR rColor: RGBColor);
  45893.  
  45894. The HSL2RGB procedure converts an HSLColor record to an RGBcolor record.
  45895.  
  45896. PROCEDURE  HSV2RGB (hColor: HSVColor; VAR rColor: RGBColor);
  45897.  
  45898. The HSV2RGB procedure converts an HSVColor record to an RGBColor record.
  45899.  
  45900. PROCEDURE  RGB2CMY (rColor: RGBColor; VAR cColor: CMYColor);
  45901.  
  45902. The RGB2CMY procedure converts an RGBColor record to a CMYColor record.
  45903.  
  45904. PROCEDURE  RGB2HSL (rColor: RGBColor; VAR hColor: HSLColor);
  45905.  
  45906. The RGB2HSL procedure converts an RGBColor record to an HSLColor record.
  45907.  
  45908. PROCEDURE  RGB2HSV (rColor: RGBColor; VAR hColor: HSVColor);
  45909.  
  45910. The RGB2HSV procedure converts an RGBColor record to an HSVColor record.
  45911.  
  45912. æKY RGB2CMY
  45913. æFc Picker.h
  45914. æT Function
  45915. æTN A82E
  45916. æD pascal void RGB2CMY(const RGBColor *rColor,CMYColor *cColor)
  45917.     = {0x3F3C,0x0004,0xA82E}; 
  45918. æDT RGB2CMY((const RGBColor *) rColor,(CMYColor *) cColor);
  45919. æMM
  45920. æRI VI
  45921. æC 
  45922. These six routines offer conversions between RGB on the one hand and CMY, HSV,
  45923. or HSL on the other.
  45924.  
  45925. PROCEDURE  CMY2RGB (cColor: CMYColor; VAR rColor: RGBColor);
  45926.  
  45927. The CMY2RGB procedure converts a CMYColor record to an RGBColor record.
  45928.  
  45929. PROCEDURE  HSL2RGB (hColor: HSLColor; VAR rColor: RGBColor);
  45930.  
  45931. The HSL2RGB procedure converts an HSLColor record to an RGBcolor record.
  45932.  
  45933. PROCEDURE  HSV2RGB (hColor: HSVColor; VAR rColor: RGBColor);
  45934.  
  45935. The HSV2RGB procedure converts an HSVColor record to an RGBColor record.
  45936.  
  45937. PROCEDURE  RGB2CMY (rColor: RGBColor; VAR cColor: CMYColor);
  45938.  
  45939. The RGB2CMY procedure converts an RGBColor record to a CMYColor record.
  45940.  
  45941. PROCEDURE  RGB2HSL (rColor: RGBColor; VAR hColor: HSLColor);
  45942.  
  45943. The RGB2HSL procedure converts an RGBColor record to an HSLColor record.
  45944.  
  45945. PROCEDURE  RGB2HSV (rColor: RGBColor; VAR hColor: HSVColor);
  45946.  
  45947. The RGB2HSV procedure converts an RGBColor record to an HSVColor record.
  45948.  
  45949. æKY HSL2RGB
  45950. æFc Picker.h
  45951. æT Function
  45952. æTN A82E
  45953. æD pascal void HSL2RGB(const HSLColor *hColor,RGBColor *rColor)
  45954.     = {0x3F3C,0x0005,0xA82E}; 
  45955. æDT HSL2RGB((const HSLColor *) hColor,(RGBColor *) rColor);
  45956. æMM
  45957. æRI VI
  45958. æC 
  45959. These six routines offer conversions between RGB on the one hand and CMY, HSV,
  45960. or HSL on the other.
  45961.  
  45962. PROCEDURE  CMY2RGB (cColor: CMYColor; VAR rColor: RGBColor);
  45963.  
  45964. The CMY2RGB procedure converts a CMYColor record to an RGBColor record.
  45965.  
  45966. PROCEDURE  HSL2RGB (hColor: HSLColor; VAR rColor: RGBColor);
  45967.  
  45968. The HSL2RGB procedure converts an HSLColor record to an RGBcolor record.
  45969.  
  45970. PROCEDURE  HSV2RGB (hColor: HSVColor; VAR rColor: RGBColor);
  45971.  
  45972. The HSV2RGB procedure converts an HSVColor record to an RGBColor record.
  45973.  
  45974. PROCEDURE  RGB2CMY (rColor: RGBColor; VAR cColor: CMYColor);
  45975.  
  45976. The RGB2CMY procedure converts an RGBColor record to a CMYColor record.
  45977.  
  45978. PROCEDURE  RGB2HSL (rColor: RGBColor; VAR hColor: HSLColor);
  45979.  
  45980. The RGB2HSL procedure converts an RGBColor record to an HSLColor record.
  45981.  
  45982. PROCEDURE  RGB2HSV (rColor: RGBColor; VAR hColor: HSVColor);
  45983.  
  45984. The RGB2HSV procedure converts an RGBColor record to an HSVColor record.
  45985.  
  45986. æKY RGB2HSL
  45987. æFc Picker.h
  45988. æT Function
  45989. æTN A82E
  45990. æD pascal void RGB2HSL(const RGBColor *rColor,HSLColor *hColor)
  45991.     = {0x3F3C,0x0006,0xA82E}; 
  45992. æDT RGB2HSL((const RGBColor *) rColor,(HSLColor *) hColor);
  45993. æMM
  45994. æRI VI
  45995. æC 
  45996. These six routines offer conversions between RGB on the one hand and CMY, HSV,
  45997. or HSL on the other.
  45998.  
  45999. PROCEDURE  CMY2RGB (cColor: CMYColor; VAR rColor: RGBColor);
  46000.  
  46001. The CMY2RGB procedure converts a CMYColor record to an RGBColor record.
  46002.  
  46003. PROCEDURE  HSL2RGB (hColor: HSLColor; VAR rColor: RGBColor);
  46004.  
  46005. The HSL2RGB procedure converts an HSLColor record to an RGBcolor record.
  46006.  
  46007. PROCEDURE  HSV2RGB (hColor: HSVColor; VAR rColor: RGBColor);
  46008.  
  46009. The HSV2RGB procedure converts an HSVColor record to an RGBColor record.
  46010.  
  46011. PROCEDURE  RGB2CMY (rColor: RGBColor; VAR cColor: CMYColor);
  46012.  
  46013. The RGB2CMY procedure converts an RGBColor record to a CMYColor record.
  46014.  
  46015. PROCEDURE  RGB2HSL (rColor: RGBColor; VAR hColor: HSLColor);
  46016.  
  46017. The RGB2HSL procedure converts an RGBColor record to an HSLColor record.
  46018.  
  46019. PROCEDURE  RGB2HSV (rColor: RGBColor; VAR hColor: HSVColor);
  46020.  
  46021. The RGB2HSV procedure converts an RGBColor record to an HSVColor record.
  46022.  
  46023. æKY HSV2RGB
  46024. æFc Picker.h
  46025. æT Function
  46026. æTN A82E
  46027. æD pascal void HSV2RGB(const HSVColor *hColor,RGBColor *rColor)
  46028.     = {0x3F3C,0x0007,0xA82E}; 
  46029. æDT HSV2RGB((const HSVColor *) hColor,(RGBColor *) rColor);
  46030. æMM
  46031. æRI VI
  46032. æC 
  46033. These six routines offer conversions between RGB on the one hand and CMY, HSV,
  46034. or HSL on the other.
  46035.  
  46036. PROCEDURE  CMY2RGB (cColor: CMYColor; VAR rColor: RGBColor);
  46037.  
  46038. The CMY2RGB procedure converts a CMYColor record to an RGBColor record.
  46039.  
  46040. PROCEDURE  HSL2RGB (hColor: HSLColor; VAR rColor: RGBColor);
  46041.  
  46042. The HSL2RGB procedure converts an HSLColor record to an RGBcolor record.
  46043.  
  46044. PROCEDURE  HSV2RGB (hColor: HSVColor; VAR rColor: RGBColor);
  46045.  
  46046. The HSV2RGB procedure converts an HSVColor record to an RGBColor record.
  46047.  
  46048. PROCEDURE  RGB2CMY (rColor: RGBColor; VAR cColor: CMYColor);
  46049.  
  46050. The RGB2CMY procedure converts an RGBColor record to a CMYColor record.
  46051.  
  46052. PROCEDURE  RGB2HSL (rColor: RGBColor; VAR hColor: HSLColor);
  46053.  
  46054. The RGB2HSL procedure converts an RGBColor record to an HSLColor record.
  46055.  
  46056. PROCEDURE  RGB2HSV (rColor: RGBColor; VAR hColor: HSVColor);
  46057.  
  46058. The RGB2HSV procedure converts an RGBColor record to an HSVColor record.
  46059.  
  46060. æKY RGB2HSV
  46061. æFc Picker.h
  46062. æT Function
  46063. æTN A82E
  46064. æD pascal void RGB2HSV(const RGBColor *rColor,HSVColor *hColor)
  46065.     = {0x3F3C,0x0008,0xA82E}; 
  46066. æDT RGB2HSV((const RGBColor *) rColor,(HSVColor *) hColor);
  46067. æMM
  46068. æRI VI
  46069. æC 
  46070. These six routines offer conversions between RGB on the one hand and CMY, HSV,
  46071. or HSL on the other.
  46072.  
  46073. PROCEDURE  CMY2RGB (cColor: CMYColor; VAR rColor: RGBColor);
  46074.  
  46075. The CMY2RGB procedure converts a CMYColor record to an RGBColor record.
  46076.  
  46077. PROCEDURE  HSL2RGB (hColor: HSLColor; VAR rColor: RGBColor);
  46078.  
  46079. The HSL2RGB procedure converts an HSLColor record to an RGBcolor record.
  46080.  
  46081. PROCEDURE  HSV2RGB (hColor: HSVColor; VAR rColor: RGBColor);
  46082.  
  46083. The HSV2RGB procedure converts an HSVColor record to an RGBColor record.
  46084.  
  46085. PROCEDURE  RGB2CMY (rColor: RGBColor; VAR cColor: CMYColor);
  46086.  
  46087. The RGB2CMY procedure converts an RGBColor record to a CMYColor record.
  46088.  
  46089. PROCEDURE  RGB2HSL (rColor: RGBColor; VAR hColor: HSLColor);
  46090.  
  46091. The RGB2HSL procedure converts an RGBColor record to an HSLColor record.
  46092.  
  46093. PROCEDURE  RGB2HSV (rColor: RGBColor; VAR hColor: HSVColor);
  46094.  
  46095. The RGB2HSV procedure converts an RGBColor record to an HSVColor record.
  46096.  
  46097. æKY GetColor
  46098. æFc Picker.h
  46099. æT Function
  46100. æTN A82E
  46101. æD pascal Boolean GetColor(Point where,const Str255 prompt,const RGBColor *inColor,
  46102.     RGBColor *outColor)
  46103.     = {0x3F3C,0x0009,0xA82E}; 
  46104. æDT Boolean myVariable = GetColor((Point) where,(const Str255) prompt,(const RGBColor *) inColor,(
  46105.     RGBColor) * outColor);
  46106. æMM
  46107. æRI VI
  46108. æC 
  46109. The GetColor function displays the Color Picker dialog box on the screen, with
  46110. its upper-left corner located at the point you designate with the where
  46111. parameter. The Color Picker Package will display the dialog box and accept color
  46112. selection on any screen, not just the main screen. If where = (0,0), the dialog
  46113. box is positioned neatly on the main screen—centered horizontally and with
  46114. one-third of the empty space above the box and two-thirds below, whatever the
  46115. screen size. If an application supplies a where parameter of -1,-1, the Color
  46116. Picker will center the dialog box on what the Color Picker determines to be the
  46117. best screen, maximizing for depth and color.  
  46118.  
  46119. The prompt string is displayed in the upper-left corner of the dialog box. The
  46120. inColor parameter is the starting color, which the user may want for comparison;
  46121. it is displayed immediately below the current output color (the one the user is
  46122. picking). The OutColor parameter is set to the last color value the user picks,
  46123. if and only if the user clicks OK. On entry, it is treated as undefined, so the
  46124. output color sample originally matches the input. Although the color being
  46125. picked may vary widely, the input color sample remains fixed, and clicking in
  46126. the input sample resets the output color sample to match it.
  46127.  
  46128. GetColor returns TRUE if the user exits by clicking the OK button or FALSE if
  46129. the user cancels.
  46130.  
  46131. Assembly-language note:  
  46132.  
  46133. Constants
  46134.  
  46135. Fix2SmallFract  .EQU  1  ; selector for Fix2SmallFract
  46136. SmallFract2Fix  .EQU  2  ; selector for mallFract2Fix
  46137. CMY2RGB         .EQU  3  ; selector for CMY2RGB
  46138. RGB2CMY         .EQU  4  ; selector for RGB2CMY
  46139. HSL2RGB         .EQU  5  ; selector for HSL2RGB
  46140. RGB2HSL         .EQU  6  ; selector for RGB2HSL
  46141. HSV2RGB         .EQU  7  ; selector for HSV2RGB
  46142. RGB2HSV         .EQU  8  ; selector for RGB2HSV
  46143. GetColor        .EQU  9  ; selector for GetColor
  46144.  
  46145. Macro
  46146.   _Pack12
  46147.  
  46148.  
  46149. æKY Power.h
  46150. æKL AOff
  46151. AOn
  46152. AOnIgnoreModem
  46153. BOff
  46154. BOn
  46155. BOnIgnoreModem
  46156. DisableIdle
  46157. EnableIdle
  46158. GetCPUSpeed
  46159. IdleUpdate
  46160. PMOp
  46161. SleepQInstall
  46162. SleepQRemove
  46163.  
  46164. BatteryByte
  46165. batteryDeadBit
  46166. batteryDeadMask
  46167. batteryLowBit
  46168. batteryLowMask
  46169. batteryRead
  46170. chargeOverFlowBit
  46171. chargeOverFlowMask
  46172. chargerConnBit
  46173. chargerConnMask
  46174. connChangedBit
  46175. connChangedMask
  46176. disableWakeUp
  46177. hiChargeBit
  46178. hiChargeMask
  46179. ModemByte
  46180. modemInstalledBit
  46181. modemInstalledMask
  46182. modemOnBit
  46183. modemOnHookBit
  46184. modemOnHookMask
  46185. modemOnMask
  46186. modemRead
  46187. noCalls
  46188. noRequest
  46189. pmBusyErr
  46190. pmDevEnableBit
  46191. pmDevEnableMask
  46192. pmModemBit
  46193. pmModemMask
  46194. PMParamBlock
  46195. PMParamBlockPtr
  46196. pmRecvEndErr
  46197. pmRecvStartErr
  46198. pmReplyTOErr
  46199. PMResultCode
  46200. pmSCCBit
  46201. pmSCCMask
  46202. pmSendEndErr
  46203. pmSendStartErr
  46204. pmSerialBit
  46205. pmSerialMask
  46206. pmVoltBit
  46207. pmVoltMask
  46208. PowerClockByte
  46209. powerCntl
  46210. powerRead
  46211. readWakeUp
  46212. ringDetectBit
  46213. ringDetectMask
  46214. ringWakeUpBit
  46215. ringWakeUpMask
  46216. setWakeUp
  46217. SleepQRec
  46218. SleepQRecPtr
  46219.  
  46220. æKY pmBusyErr
  46221. æFc Power.h
  46222. æT #define
  46223. æD 
  46224. /* PMgrResultCode values */
  46225.  
  46226. #define pmBusyErr -13000 /* PMgr stuck busy */
  46227. æC 
  46228.  
  46229. æKY pmReplyTOErr
  46230. æFc Power.h
  46231. æT #define
  46232. æD #define pmReplyTOErr -13001 /* Timed out waiting to begin reply handshake */
  46233. æC 
  46234.  
  46235. æKY pmSendStartErr
  46236. æFc Power.h
  46237. æT #define
  46238. æD #define pmSendStartErr -13002 /* PMgr did not start handshake */
  46239. æC 
  46240.  
  46241. æKY pmSendEndErr
  46242. æFc Power.h
  46243. æT #define
  46244. æD #define pmSendEndErr -13003 /* During send, PMgr did not finish handshake */
  46245. æC 
  46246.  
  46247. æKY pmRecvStartErr
  46248. æFc Power.h
  46249. æT #define
  46250. æD #define pmRecvStartErr -13004 /* During receive, PMgr did not start handshake */
  46251. æC 
  46252.  
  46253. æKY pmRecvEndErr
  46254. æFc Power.h
  46255. æT #define
  46256. æD #define pmRecvEndErr -13005 /* During receive, PMgr did not finish handshake */
  46257. æC 
  46258.  
  46259. æKY pmSCCBit
  46260. æFc Power.h
  46261. æT #define
  46262. æD 
  46263. /* bit positions for PowerClockByte */
  46264.  
  46265. #define pmSCCBit 1 /*SCC clock*/
  46266. æC 
  46267.  
  46268. æKY pmModemBit
  46269. æFc Power.h
  46270. æT #define
  46271. æD #define pmModemBit 3 /*Internal modem power*/
  46272. æC 
  46273.  
  46274. æKY pmSerialBit
  46275. æFc Power.h
  46276. æT #define
  46277. æD #define pmSerialBit 4 /*Serial drivers power*/
  46278. æC 
  46279.  
  46280. æKY pmVoltBit
  46281. æFc Power.h
  46282. æT #define
  46283. æD #define pmVoltBit 6 /*-5 volt power*/
  46284. æC 
  46285.  
  46286. æKY pmDevEnableBit
  46287. æFc Power.h
  46288. æT #define
  46289. æD #define pmDevEnableBit 7
  46290. æC 
  46291.  
  46292. æKY pmSCCMask
  46293. æFc Power.h
  46294. æT #define
  46295. æD 
  46296. /* Masks for PowerClockByte */
  46297.  
  46298. #define pmSCCMask 0x2
  46299. æC 
  46300.  
  46301. æKY pmModemMask
  46302. æFc Power.h
  46303. æT #define
  46304. æD #define pmModemMask 0x8
  46305. æC 
  46306.  
  46307. æKY pmSerialMask
  46308. æFc Power.h
  46309. æT #define
  46310. æD #define pmSerialMask 0x10
  46311. æC 
  46312.  
  46313. æKY pmVoltMask
  46314. æFc Power.h
  46315. æT #define
  46316. æD #define pmVoltMask 0x40
  46317. æC 
  46318.  
  46319. æKY pmDevEnableMask
  46320. æFc Power.h
  46321. æT #define
  46322. æD #define pmDevEnableMask 0x80
  46323. æC 
  46324.  
  46325. æKY modemOnBit
  46326. æFc Power.h
  46327. æT #define
  46328. æD 
  46329. /* Bit positions for ModemByte */
  46330.  
  46331. #define modemOnBit 0
  46332. æC 
  46333.  
  46334. æKY ringWakeUpBit
  46335. æFc Power.h
  46336. æT #define
  46337. æD #define ringWakeUpBit 2
  46338. æC 
  46339.  
  46340. æKY modemInstalledBit
  46341. æFc Power.h
  46342. æT #define
  46343. æD #define modemInstalledBit 3
  46344. æC 
  46345.  
  46346. æKY ringDetectBit
  46347. æFc Power.h
  46348. æT #define
  46349. æD #define ringDetectBit 4
  46350. æC 
  46351.  
  46352. æKY modemOnHookBit
  46353. æFc Power.h
  46354. æT #define
  46355. æD #define modemOnHookBit 5
  46356. æC 
  46357.  
  46358. æKY modemOnMask
  46359. æFc Power.h
  46360. æT #define
  46361. æD 
  46362. /* masks for ModemByte */
  46363.  
  46364. #define modemOnMask 0x1
  46365. æC 
  46366.  
  46367. æKY ringWakeUpMask
  46368. æFc Power.h
  46369. æT #define
  46370. æD #define ringWakeUpMask 0x4
  46371. æC 
  46372.  
  46373. æKY modemInstalledMask
  46374. æFc Power.h
  46375. æT #define
  46376. æD #define modemInstalledMask 0x8
  46377. æC 
  46378.  
  46379. æKY ringDetectMask
  46380. æFc Power.h
  46381. æT #define
  46382. æD #define ringDetectMask 0x10
  46383. æC 
  46384.  
  46385. æKY modemOnHookMask
  46386. æFc Power.h
  46387. æT #define
  46388. æD #define modemOnHookMask 0x20
  46389. æC 
  46390.  
  46391. æKY chargerConnBit
  46392. æFc Power.h
  46393. æT #define
  46394. æD 
  46395. /* bit positions for BatteryByte */
  46396.  
  46397. #define chargerConnBit 0
  46398. æC 
  46399.  
  46400. æKY hiChargeBit
  46401. æFc Power.h
  46402. æT #define
  46403. æD #define hiChargeBit 1
  46404. æC 
  46405.  
  46406. æKY chargeOverFlowBit
  46407. æFc Power.h
  46408. æT #define
  46409. æD #define chargeOverFlowBit 2
  46410. æC 
  46411.  
  46412. æKY batteryDeadBit
  46413. æFc Power.h
  46414. æT #define
  46415. æD #define batteryDeadBit 3
  46416. æC 
  46417.  
  46418. æKY batteryLowBit
  46419. æFc Power.h
  46420. æT #define
  46421. æD #define batteryLowBit 4
  46422. æC 
  46423.  
  46424. æKY connChangedBit
  46425. æFc Power.h
  46426. æT #define
  46427. æD #define connChangedBit 5
  46428. æC 
  46429.  
  46430. æKY chargerConnMask
  46431. æFc Power.h
  46432. æT #define
  46433. æD 
  46434. /* masks for BatteryByte */
  46435.  
  46436. #define chargerConnMask 0x1
  46437. æC 
  46438.  
  46439. æKY hiChargeMask
  46440. æFc Power.h
  46441. æT #define
  46442. æD #define hiChargeMask 0x2
  46443. æC 
  46444.  
  46445. æKY chargeOverFlowMask
  46446. æFc Power.h
  46447. æT #define
  46448. æD #define chargeOverFlowMask 0x4
  46449. æC 
  46450.  
  46451. æKY batteryDeadMask
  46452. æFc Power.h
  46453. æT #define
  46454. æD #define batteryDeadMask 0x8
  46455. æC 
  46456.  
  46457. æKY batteryLowMask
  46458. æFc Power.h
  46459. æT #define
  46460. æD #define batteryLowMask 0x10
  46461. æC 
  46462.  
  46463. æKY connChangedMask
  46464. æFc Power.h
  46465. æT #define
  46466. æD #define connChangedMask 0x20
  46467. æC 
  46468.  
  46469. æKY powerCntl
  46470. æFc Power.h
  46471. æT #define
  46472. æD 
  46473. /* Commands for PMOp function */
  46474.  
  46475. #define powerCntl 0x10 /* Power/clock control */
  46476. æC 
  46477.  
  46478. æKY powerRead
  46479. æFc Power.h
  46480. æT #define
  46481. æD #define powerRead 0x18 /* Power/clock control */
  46482. æC 
  46483.  
  46484. æKY modemRead
  46485. æFc Power.h
  46486. æT #define
  46487. æD #define modemRead 0x58 /* Internal modem setup */
  46488. æC 
  46489.  
  46490. æKY batteryRead
  46491. æFc Power.h
  46492. æT #define
  46493. æD #define batteryRead 0x68 /* Battery/charger level and status */
  46494. æC 
  46495.  
  46496. æKY setWakeUp
  46497. æFc Power.h
  46498. æT #define
  46499. æD #define setWakeUp 0x80 /* Set Wake-up timer */
  46500. æC 
  46501.  
  46502. æKY disableWakeUp
  46503. æFc Power.h
  46504. æT #define
  46505. æD #define disableWakeUp 0x82 /* Disable Wake-up timer */
  46506. æC 
  46507.  
  46508. æKY readWakeUp
  46509. æFc Power.h
  46510. æT #define
  46511. æD #define readWakeUp 0x88 /* Read Wake-up timer */
  46512. æC 
  46513.  
  46514. æKY noCalls
  46515. æFc Power.h
  46516. æT #define
  46517. æD 
  46518. /* SleepQRec.sleepQFlags */
  46519.  
  46520. #define noCalls 1
  46521. æC 
  46522.  
  46523. æKY noRequest
  46524. æFc Power.h
  46525. æT #define
  46526. æD #define noRequest 2
  46527. æC 
  46528.  
  46529. æKY PowerClockByte
  46530. æFc Power.h
  46531. æT typedef
  46532. æD typedef char PowerClockByte;
  46533. æC 
  46534.  
  46535. æKY ModemByte
  46536. æFc Power.h
  46537. æT typedef
  46538. æD typedef char ModemByte;
  46539. æC 
  46540.  
  46541. æKY BatteryByte
  46542. æFc Power.h
  46543. æT typedef
  46544. æD typedef char BatteryByte;
  46545. æC 
  46546.  
  46547. æKY PMResultCode
  46548. æFc Power.h
  46549. æT typedef
  46550. æD 
  46551. typedef long PMResultCode;
  46552. æC 
  46553.  
  46554. æKY PMParamBlock
  46555. PMParamBlockPtr
  46556. æFc Power.h
  46557. æT struct
  46558. æD struct PMParamBlock {
  46559.     short pmCommand;
  46560.     short pmCount;
  46561.     Ptr pmSendBuff;
  46562.     Ptr pmReceiveBuff;
  46563. };
  46564.  
  46565. typedef struct PMParamBlock PMParamBlock;
  46566. typedef PMParamBlock *PMParamBlockPtr;
  46567.  
  46568. æC 
  46569.  
  46570. æKY SleepQRec
  46571. SleepQRecPtr
  46572. æFc Power.h
  46573. æT struct
  46574. æD struct SleepQRec {
  46575.     struct SleepQRec *sleepQLink;
  46576.     short sleepQType; /*type = 16*/
  46577.     ProcPtr sleepQProc; /*Pointer to sleep routine*/
  46578.     short sleepQFlags;
  46579. };
  46580.  
  46581. typedef struct SleepQRec SleepQRec;
  46582. typedef SleepQRec *SleepQRecPtr;
  46583.  
  46584. æC 
  46585.  
  46586. æKY PMOp
  46587. æFc Power.h
  46588. æT Function
  46589. æTN A085
  46590. æD PMResultCode PMOp(PMParamBlockPtr pBlockPtr)
  46591.     = {0x205F,0xA085}; 
  46592. æDT PMResultCode myVariable = PMOp((PMParamBlockPtr) pBlockPtr);
  46593. æC 
  46594. Assembly-Language Notes:
  46595.  
  46596. Constants
  46597.  
  46598. ;Commands for PMOp function
  46599. powerCntl       .EQU  $10  ;power/clock control 
  46600. powerRead       .EQU  $18  ;power/clock control 
  46601. modemRead       .EQU  $58  ;internal modem setup 
  46602. batteryRead     .EQU  $68  ;battery/charger level and status 
  46603. setWakeUp       .EQU  $80  ;set wakeup timer 
  46604. disableWakeUp   .EQU  $82  ;disable wakeup timer 
  46605. readWakeUp      .EQU  $88  ;read wakeup timer 
  46606.  
  46607. æKY IdleUpdate
  46608. æFc Power.h
  46609. æT Function
  46610. æTN A285
  46611. æD long IdleUpdate(void)
  46612.     = 0xA285; 
  46613. æDT long myVariable = IdleUpdate()(void);
  46614. æC 
  46615. The IdleUpdate function takes no parameters. It returns the value in the Ticks
  46616. global variable at the time the function was called. 
  46617.  
  46618. æKY GetCPUSpeed
  46619. æFc Power.h
  46620. æT Function
  46621. æTN A485
  46622. æD long GetCPUSpeed(void)
  46623.     = {0x70FF,0xA485}; 
  46624. æDT long myVariable = GetCPUSpeed()(void);
  46625. æC 
  46626. Trap macro  _IdleState
  46627. On entry  D0: any negative number
  46628. On exit  D0: the CPU clock speed; $1 or $10
  46629.  
  46630. The GetCPUSpeed function returns the current effective clock speed of the CPU.
  46631. The only values that are returned by this function are 1 and 16, indicating the
  46632. clock speed in megahertz.
  46633.  
  46634. æKY EnableIdle
  46635. æFc Power.h
  46636. æT Function
  46637. æTN A485
  46638. æD void EnableIdle(void)
  46639.     = {0x7000,0xA485}; 
  46640. æDT EnableIdle()(void);
  46641. æC 
  46642. Trap macro  _IdleState
  46643. On entry  D0: 0
  46644.  
  46645. The EnableIdle procedure cancels the effect of a call to the DisableIdle
  46646. procedure. A call to the EnableIdle procedure enables the idle state only if the
  46647. user has not used the Portable control panel to disable the idle state and every
  46648. call to the DisableIdle procedure has been balanced by a call to the EnableIdle
  46649. procedure.
  46650.  
  46651. æKY DisableIdle
  46652. æFc Power.h
  46653. æT Function
  46654. æTN A485
  46655. æD void DisableIdle(void)
  46656.     = {0x7001,0xA485}; 
  46657. æDT DisableIdle()(void);
  46658. æC 
  46659. Trap macro  _IdleState
  46660. On entry  D0: any positive number
  46661.  
  46662. The DisableIdle procedure disables the idle state, even if the user has used the
  46663. Portable control panel to enable the idle state. Every call to the DisableIdle
  46664. procedure must be balanced by a call to the EnableIdle procedure before the idle
  46665. state is reenabled.
  46666.  
  46667. æKY SleepQInstall
  46668. æFc Power.h
  46669. æT Function
  46670. æTN A28A
  46671. æD void SleepQInstall(SleepQRecPtr qRecPtr)
  46672.     = {0x205F,0xA28A}; 
  46673. æDT SleepQInstall((SleepQRecPtr) qRecPtr);
  46674. æC 
  46675. You can use the SleepQInstall procedure to add an enty to the sleep queue, and
  46676. you can use the SleepQRemove procedure to remove an entry from the sleep queue.
  46677.  
  46678. The qRecPtr parameter is a pointer to a sleep queue record that you must
  46679. provide. The structure of a sleep queue record is shown in “Placing a Routine in
  46680. the Sleep Queue,” earlier in this chapter.
  46681.  
  46682. æKY SleepQRemove
  46683. æFc Power.h
  46684. æT Function
  46685. æTN A48A
  46686. æD void SleepQRemove(SleepQRecPtr qRecPtr)
  46687.     = {0x205F,0xA48A}; 
  46688. æDT SleepQRemove((SleepQRecPtr) qRecPtr);
  46689. æC 
  46690. You can use the SleepQInstall procedure to add an enty to the sleep queue, and
  46691. you can use the SleepQRemove procedure to remove an entry from the sleep queue.
  46692.  
  46693. The qRecPtr parameter is a pointer to the sleep queue record that you provided
  46694. when you added your routine to the sleep queue.
  46695.  
  46696. æKY AOn
  46697. æFc Power.h
  46698. æT Function
  46699. æTN A685
  46700. æD void AOn(void)
  46701.     = {0x7004,0xA685}; 
  46702. æDT AOn()(void);
  46703. æC 
  46704. There are six procedures to control power to the serial ports and internal
  46705. modem. Although at present there is no way for the user to connect the internal
  46706. modem to serial port B, the Power Manager supports this configuration in case it
  46707. becomes available in the future.
  46708.  
  46709. Trap macro  _SerialPower
  46710. On entry  D0: $04
  46711.  
  46712. The AOn procedure always switches on power to the SCC and the –5 volt supply. If
  46713. the internal modem is installed and is connected to port A, this procedure also
  46714. switches on power to the modem. If either of these conditions is not met, it
  46715. switches on power to the serial driver chips.
  46716.  
  46717. æKY AOnIgnoreModem
  46718. æFc Power.h
  46719. æT Function
  46720. æTN A685
  46721. æD void AOnIgnoreModem(void)
  46722.     = {0x7005,0xA685}; 
  46723. æDT AOnIgnoreModem()(void);
  46724. æC 
  46725. Trap macro  _SerialPower
  46726. On entry  D0: $05
  46727.  
  46728. The AOnIgnoreModem procedure switches on power to the SCC, the –5 volt supply,
  46729. and the serial driver chips. This procedure does not switch on power to the
  46730. internal modem, even if the user has connected it to port A through the Portable
  46731. control panel.
  46732.  
  46733. æKY BOn
  46734. æFc Power.h
  46735. æT Function
  46736. æTN A685
  46737. æD void BOn(void)
  46738.     = {0x7000,0xA685}; 
  46739. æDT BOn()(void);
  46740. æC 
  46741. Trap macro  _SerialPower
  46742. On entry  D0: $00
  46743.  
  46744. The BOn procedure always switches on power to the SCC and the –5 volt supply. If
  46745. the internal modem is installed and is connected to port B, this procedure also
  46746. switches on power to the modem. If either of these conditions is not met, it
  46747. switches on power to the serial driver chips.
  46748.  
  46749. æKY BOnIgnoreModem
  46750. æFc Power.h
  46751. æT Function
  46752. æTN A685
  46753. æD void BOnIgnoreModem(void)
  46754.     = {0x7001,0xA685}; 
  46755. æDT BOnIgnoreModem()(void);
  46756. æC 
  46757. Trap macro  _SerialPower
  46758. On entry  D0: $01
  46759.  
  46760. The BOnIgnoreModem procedure switches on power to the SCC, the –5 volt supply,
  46761. and the serial driver chips. This procedure does not switch on power to the
  46762. internal modem, even if the user has connected it to port B. Currently there is
  46763. no way for the user to connect the modem to port B.
  46764.  
  46765. æKY AOff
  46766. æFc Power.h
  46767. æT Function
  46768. æTN A685
  46769. æD void AOff(void)
  46770.     = {0x7084,0xA685}; 
  46771. æDT AOff()(void);
  46772. æC 
  46773. Trap macro  _SerialPower
  46774. On entry  D0: $84
  46775.  
  46776. The AOff procedure always switches off power to the SCC and the –5 volt supply
  46777. if serial port B is not in use. If the internal modem is installed, connected to
  46778. port A, and switched on, this procedure switches off power to the modem. If any
  46779. of these conditions are not met, it switches off power to the serial driver
  46780. chips, unless they are being used by port B.
  46781.  
  46782. æKY BOff
  46783. æFc Power.h
  46784. æT Function
  46785. æTN A685
  46786. æD void BOff(void)
  46787.     = {0x7080,0xA685}; 
  46788. æDT BOff()(void);
  46789. æC 
  46790. Trap macro  _SerialPower
  46791. On entry  D0: $80
  46792.  
  46793. The BOff procedure switches off power to the SCC and the –5 volt supply if
  46794. serial port A is not in use. If the internal modem is installed, connected to
  46795. port B, and switched on, this procedure switches off power to the modem.
  46796. Otherwise it switches off power to the serial driver chips, unless they are
  46797. being used by port A.
  46798.  
  46799.  
  46800. æKY PPCToolBox.h
  46801. æKL DeleteUserIdentity
  46802. GetDefaultUser
  46803. IPCListPorts
  46804. PPCBrowser
  46805. PPCClose
  46806. PPCEnd
  46807. PPCInform
  46808. PPCInit
  46809. PPCOpen
  46810. PPCRead
  46811. PPCReject
  46812. PPCStart
  46813. PPCWrite
  46814. PromptForUserIdentity
  46815. StartSecureSession
  46816.  
  46817. atalkPhaseErr
  46818. Authenticate
  46819. authFailErr
  46820. badLocNameErr
  46821. badPortNameErr
  46822. badReqErr
  46823. badServiceMethodErr
  46824. Both
  46825. destPortErr
  46826. DontAuthenticate
  46827. DontCare
  46828. guestNotAllowedErr
  46829. IPCListPortParams
  46830. IPCListPortParamsPtr
  46831. localOnlyErr
  46832. LocalRequest
  46833. LocName
  46834. LocNamePtr
  46835. loginCancelErr
  46836. MacType
  46837. nameTypeErr
  46838. NasName
  46839. NbpName
  46840. networkErr
  46841. NetworkRequest
  46842. noDefaultUserErr
  46843. noGlobalsErr
  46844. noInformErr
  46845. NoLocName
  46846. noPortErr
  46847. noPortTableErr
  46848. noResponseErr
  46849. noSessionErr
  46850. notInitErr
  46851. notLoggedInErr
  46852. noToolboxNameErr
  46853. notSupportedErr
  46854. noUserNameErr
  46855. noUserRecErr
  46856. noUserRefErr
  46857. portClosedErr
  46858. PortInfo
  46859. PortInfoPtr
  46860. PortName
  46861. portNameExistsErr
  46862. PortNamePtr
  46863. PPCAcceptParams
  46864. PPCAcceptParamsPtr
  46865. PPCCloseParams
  46866. PPCCloseParamsPtr
  46867. PPCEndParams
  46868. PPCEndParamsPtr
  46869. PPCHeader
  46870. PPCInformParams
  46871. PPCOpenParams
  46872. PPCOpenParamsPtr
  46873. PPCParamBlk
  46874. PPCParamBlkPtr
  46875. PPCReadParams
  46876. PPCReadParamsPtr
  46877. PPCRejectParams
  46878. PPCRejectParamsPtr
  46879. PPCStartParams
  46880. PPCStartParamsPtr
  46881. PPCWriteParams
  46882. PPCWriteParamsPtr
  46883. RealTime
  46884. sessClosedErr
  46885. sessTableErr
  46886. StoreAndForward
  46887. StrType
  46888. tooManyPortsErr
  46889. unKnownUserErr
  46890. userRejectErr
  46891.  
  46892. æKY RealTime
  46893. æFc PPCToolBox.h
  46894. æT #define
  46895. æD 
  46896. /*  service Type  */
  46897.  
  46898. #define RealTime 1
  46899. æC 
  46900.  
  46901. æKY StoreAndForward
  46902. æFc PPCToolBox.h
  46903. æT #define
  46904. æD #define StoreAndForward 2
  46905. æC 
  46906.  
  46907. æKY DontCare
  46908. æFc PPCToolBox.h
  46909. æT #define
  46910. æD #define DontCare 3
  46911. æC 
  46912.  
  46913. æKY Both
  46914. æFc PPCToolBox.h
  46915. æT #define
  46916. æD #define Both 4
  46917. æC 
  46918.  
  46919. æKY NoLocName
  46920. æFc PPCToolBox.h
  46921. æT #define
  46922. æD 
  46923. /*  lookup Type  */
  46924.  
  46925. #define NoLocName 0 /* There is no PPCLocName */
  46926. æC 
  46927.  
  46928. æKY NbpName
  46929. æFc PPCToolBox.h
  46930. æT #define
  46931. æD #define NbpName 1 /* Use AppleTalk NBP      */
  46932. æC 
  46933.  
  46934. æKY NasName
  46935. æFc PPCToolBox.h
  46936. æT #define
  46937. æD #define NasName 2 /* Use Name and Authentication Service */
  46938. æC 
  46939.  
  46940. æKY MacType
  46941. æFc PPCToolBox.h
  46942. æT #define
  46943. æD 
  46944. /*  port Types
  46945.  */
  46946.  
  46947. #define MacType 1 /* PortType is specified as standars mac creator and type */
  46948. æC 
  46949.  
  46950. æKY StrType
  46951. æFc PPCToolBox.h
  46952. æT #define
  46953. æD #define StrType 2 /* Port Type is in pascal string format */
  46954. æC 
  46955.  
  46956. æKY Authenticate
  46957. æFc PPCToolBox.h
  46958. æT #define
  46959. æD 
  46960. /*  Authentication Requests  */
  46961.  
  46962. #define Authenticate 1 /* Authenticate incomming network requets */
  46963. æC 
  46964.  
  46965. æKY DontAuthenticate
  46966. æFc PPCToolBox.h
  46967. æT #define
  46968. æD #define DontAuthenticate 0 /* Don't Authenticate */
  46969. æC 
  46970.  
  46971. æKY LocalRequest
  46972. æFc PPCToolBox.h
  46973. æT #define
  46974. æD 
  46975. /*  Values returned for requestType field in PPCInform call */
  46976.  
  46977. #define LocalRequest 1
  46978. æC 
  46979.  
  46980. æKY NetworkRequest
  46981. æFc PPCToolBox.h
  46982. æT #define
  46983. æD #define NetworkRequest 2
  46984. æC 
  46985.  
  46986. æKY notInitErr
  46987. æFc PPCToolBox.h
  46988. æT #define
  46989. æD 
  46990. /*  ------------------------------------- 
  46991.  -900 to -950 are reserved for PPC      */
  46992.  
  46993. #define notInitErr -900
  46994. æC 
  46995.  
  46996. æKY tooManyPortsErr
  46997. æFc PPCToolBox.h
  46998. æT #define
  46999. æD #define tooManyPortsErr -901
  47000. æC 
  47001.  
  47002. æKY nameTypeErr
  47003. æFc PPCToolBox.h
  47004. æT #define
  47005. æD #define nameTypeErr -902
  47006. æC 
  47007.  
  47008. æKY noPortErr
  47009. æFc PPCToolBox.h
  47010. æT #define
  47011. æD #define noPortErr -903
  47012. æC 
  47013.  
  47014. æKY noGlobalsErr
  47015. æFc PPCToolBox.h
  47016. æT #define
  47017. æD #define noGlobalsErr -904
  47018. æC 
  47019.  
  47020. æKY localOnlyErr
  47021. æFc PPCToolBox.h
  47022. æT #define
  47023. æD #define localOnlyErr -905
  47024. æC 
  47025.  
  47026. æKY destPortErr
  47027. æFc PPCToolBox.h
  47028. æT #define
  47029. æD #define destPortErr -906
  47030. æC 
  47031.  
  47032. æKY sessTableErr
  47033. æFc PPCToolBox.h
  47034. æT #define
  47035. æD #define sessTableErr -907
  47036. æC 
  47037.  
  47038. æKY noSessionErr
  47039. æFc PPCToolBox.h
  47040. æT #define
  47041. æD #define noSessionErr -908
  47042. æC 
  47043.  
  47044. æKY badReqErr
  47045. æFc PPCToolBox.h
  47046. æT #define
  47047. æD #define badReqErr -909
  47048. æC 
  47049.  
  47050. æKY portNameExistsErr
  47051. æFc PPCToolBox.h
  47052. æT #define
  47053. æD #define portNameExistsErr -910
  47054. æC 
  47055.  
  47056. æKY noPortTableErr
  47057. æFc PPCToolBox.h
  47058. æT #define
  47059. æD #define noPortTableErr -911
  47060. æC 
  47061.  
  47062. æKY userRejectErr
  47063. æFc PPCToolBox.h
  47064. æT #define
  47065. æD #define userRejectErr -912
  47066. æC 
  47067.  
  47068. æKY noUserNameErr
  47069. æFc PPCToolBox.h
  47070. æT #define
  47071. æD #define noUserNameErr -913
  47072. æC 
  47073.  
  47074. æKY noToolboxNameErr
  47075. æFc PPCToolBox.h
  47076. æT #define
  47077. æD #define noToolboxNameErr -914
  47078. æC 
  47079.  
  47080. æKY noResponseErr
  47081. æFc PPCToolBox.h
  47082. æT #define
  47083. æD #define noResponseErr -915
  47084. æC 
  47085.  
  47086. æKY portClosedErr
  47087. æFc PPCToolBox.h
  47088. æT #define
  47089. æD #define portClosedErr -916
  47090. æC 
  47091.  
  47092. æKY sessClosedErr
  47093. æFc PPCToolBox.h
  47094. æT #define
  47095. æD #define sessClosedErr -917
  47096. æC 
  47097.  
  47098. æKY atalkPhaseErr
  47099. æFc PPCToolBox.h
  47100. æT #define
  47101. æD #define atalkPhaseErr -918 /* apple talk is not phase 2 */
  47102. æC 
  47103.  
  47104. æKY badPortNameErr
  47105. æFc PPCToolBox.h
  47106. æT #define
  47107. æD #define badPortNameErr -919
  47108. æC 
  47109.  
  47110. æKY loginCancelErr
  47111. æFc PPCToolBox.h
  47112. æT #define
  47113. æD #define loginCancelErr -920
  47114. æC 
  47115.  
  47116. æKY unKnownUserErr
  47117. æFc PPCToolBox.h
  47118. æT #define
  47119. æD #define unKnownUserErr -921
  47120. æC 
  47121.  
  47122. æKY noDefaultUserErr
  47123. æFc PPCToolBox.h
  47124. æT #define
  47125. æD #define noDefaultUserErr -922
  47126. æC 
  47127.  
  47128. æKY notLoggedInErr
  47129. æFc PPCToolBox.h
  47130. æT #define
  47131. æD #define notLoggedInErr -923
  47132. æC 
  47133.  
  47134. æKY noUserRefErr
  47135. æFc PPCToolBox.h
  47136. æT #define
  47137. æD #define noUserRefErr -924
  47138. æC 
  47139.  
  47140. æKY networkErr
  47141. æFc PPCToolBox.h
  47142. æT #define
  47143. æD #define networkErr -925
  47144. æC 
  47145.  
  47146. æKY noInformErr
  47147. æFc PPCToolBox.h
  47148. æT #define
  47149. æD #define noInformErr -926
  47150. æC 
  47151.  
  47152. æKY authFailErr
  47153. æFc PPCToolBox.h
  47154. æT #define
  47155. æD #define authFailErr -927
  47156. æC 
  47157.  
  47158. æKY noUserRecErr
  47159. æFc PPCToolBox.h
  47160. æT #define
  47161. æD #define noUserRecErr -928
  47162. æC 
  47163.  
  47164. æKY notSupportedErr
  47165. æFc PPCToolBox.h
  47166. æT #define
  47167. æD #define notSupportedErr -929
  47168. æC 
  47169.  
  47170. æKY badServiceMethodErr
  47171. æFc PPCToolBox.h
  47172. æT #define
  47173. æD #define badServiceMethodErr -930
  47174. æC 
  47175.  
  47176. æKY badLocNameErr
  47177. æFc PPCToolBox.h
  47178. æT #define
  47179. æD #define badLocNameErr -931
  47180. æC 
  47181.  
  47182. æKY guestNotAllowedErr
  47183. æFc PPCToolBox.h
  47184. æT #define
  47185. æD #define guestNotAllowedErr -932
  47186. æC 
  47187.  
  47188. æKY PPCHeader
  47189. æFc PPCToolBox.h
  47190. æT typedef
  47191. æD #define PPCHeader \
  47192.      Ptr               qLink;             /* PPC's Internal Use */\
  47193.      unsigned short    cmdCode;            /* Requested PPC command */\
  47194.      unsigned short    intxUse;           /* Internal Use */\
  47195.      Ptr               intxUsePtr;          /* Internal Use */\
  47196.      ProcPtr           cmdCompletion;     /* Completion Routine    */\
  47197.      OSErr               cmdResult;         /* Command Result Code */\
  47198.      unsigned long       Reserved[5];      /* Reserved for PPC, Don'tuse */ 
  47199. æC 
  47200.  
  47201. æKY PortName
  47202. PortNamePtr
  47203. æFc PPCToolBox.h
  47204. æT struct
  47205. æD struct PortName {
  47206.     unsigned short scriptCode; /* Language Identifier */
  47207.     Str32 nameStr; /* pascal name string */
  47208.     unsigned short typeSelector; /* port's type selector */
  47209.     union {
  47210.     Str32 typeStr; /* pascal type string */
  47211.     struct {
  47212.     unsigned long portCreator;
  47213.     unsigned long portType;
  47214.     } macType;
  47215.     } u;
  47216. };
  47217.  
  47218. typedef struct PortName PortName;
  47219. typedef PortName *PortNamePtr;
  47220.  
  47221. æC 
  47222.  
  47223. æKY LocName
  47224. LocNamePtr
  47225. æFc PPCToolBox.h
  47226. æT struct
  47227. æD struct LocName {
  47228.     unsigned short nameType; /* NBP or NAS name type (For Now Only NBPNAME) */
  47229.     union {
  47230.     EntityName nbpName; /* NBP name entity */
  47231.     unsigned char nasName[100];
  47232.     } u;
  47233. };
  47234.  
  47235. typedef struct LocName LocName;
  47236. typedef LocName *LocNamePtr;
  47237.  
  47238. æC 
  47239.  
  47240. æKY PPCOpenParams
  47241. PPCOpenParamsPtr
  47242. æFc PPCToolBox.h
  47243. æT struct
  47244. æD struct PPCOpenParams {
  47245.     PPCHeader 
  47246.     unsigned short portRefNum; /* Port Identifier*/
  47247.     unsigned char serviceType; /* service type RealTime or StoreAndorward or Both */
  47248.     unsigned char resFlag; /* Must be Set to Zero. Network Requests are always authentcated*/
  47249.     unsigned char networkVisible; /* make this network visible on network */
  47250.     unsigned char nbpRegistered; /* The given locname was registered on the network */
  47251.     PortNamePtr portName; /* PortName for PPC */
  47252.     LocNamePtr portLocName; /* If NBP or NAS Registration is required */
  47253. };
  47254.  
  47255. typedef struct PPCOpenParams PPCOpenParams;
  47256. typedef PPCOpenParams *PPCOpenParamsPtr;
  47257.  
  47258. æC 
  47259.  
  47260. æKY PPCInformParams
  47261. æFc PPCToolBox.h
  47262. æT struct
  47263. æD struct PPCInformParams {
  47264.      
  47265.     unsigned short portRefNum; /* Port Identifier*/
  47266.     unsigned long sessRefNum; /* Session Reference */
  47267.     Boolean autoAccept; /* if true session will be accepted automatically */
  47268.     unsigned char serviceMethod; /* service type RealTime or StoreAndorward */
  47269.     unsigned char requestType; /* 1 = Local, 2 = Network */
  47270.     unsigned long userData; /* Any Optional data sent by user */
  47271.     PortNamePtr portName; /* Destination portName */
  47272.     unsigned char *userName; /* user requesting the authentication */
  47273.     LocNamePtr portLocName; /* NBP or NAS style service location name */
  47274. };
  47275.  
  47276. typedef struct PPCInformParams PPCInformParams;
  47277. typedef PPCInformParams *PPCInformParams;
  47278.  
  47279. æC 
  47280.  
  47281. æKY PPCStartParams
  47282. PPCStartParamsPtr
  47283. æFc PPCToolBox.h
  47284. æT struct
  47285. æD struct PPCStartParams {
  47286.      
  47287.     unsigned short portRefNum; /* Port Identifier*/
  47288.     unsigned long sessRefNum; /* Session Reference */
  47289.     unsigned char serviceMethod    ; /* service type RealTime or StoreAndorward or Don't care */
  47290.     unsigned short userRefNum; /* userRefNum (obtained during login process) */
  47291.     unsigned long userData; /* Any optional data (tool box will not interpret this) */
  47292.     unsigned long rejectInfo; /* reason for rejecting the session request */
  47293.     PortNamePtr portName; /* Destination portName */
  47294.     LocNamePtr portLocName; /* NBP or NAS style service location name */
  47295. };
  47296.  
  47297. typedef struct PPCStartParams PPCStartParams;
  47298. typedef PPCStartParams *PPCStartParamsPtr;
  47299.  
  47300. æC 
  47301.  
  47302. æKY PPCAcceptParams
  47303. PPCAcceptParamsPtr
  47304. æFc PPCToolBox.h
  47305. æT struct
  47306. æD struct PPCAcceptParams {
  47307.     PPCHeader 
  47308.     unsigned short resFiller; /* Must be set to zero */
  47309.     unsigned long sessRefNum; /* Session Identifier */
  47310. };
  47311.  
  47312. typedef struct PPCAcceptParams PPCAcceptParams;
  47313. typedef PPCAcceptParams *PPCAcceptParamsPtr;
  47314.  
  47315. æC 
  47316.  
  47317. æKY PPCRejectParams
  47318. PPCRejectParamsPtr
  47319. æFc PPCToolBox.h
  47320. æT struct
  47321. æD struct PPCRejectParams {
  47322.     PPCHeader 
  47323.     unsigned short resFiller; /* Must be set to zero */
  47324.     unsigned long sessRefNum; /* Session Identifier */
  47325.     unsigned long rejectInfo; /* reason for rejecting the session request */
  47326. };
  47327.  
  47328. typedef struct PPCRejectParams PPCRejectParams;
  47329. typedef PPCRejectParams *PPCRejectParamsPtr;
  47330.  
  47331. æC 
  47332.  
  47333. æKY PPCWriteParams
  47334. PPCWriteParamsPtr
  47335. æFc PPCToolBox.h
  47336. æT struct
  47337. æD struct PPCWriteParams {
  47338.     PPCHeader 
  47339.     unsigned short resFiller; /* Must be set to zero */
  47340.     unsigned long sessRefNum; /* Session Identifier */
  47341.     unsigned long blockCreator; /* Message block creator */
  47342.     unsigned long blockType; /* Message block type */
  47343.     unsigned long bufferLength; /* Length of the message buffer */
  47344.     unsigned long actualLength; /* Actual Length Written */
  47345.     unsigned long userData; /* User can pass anything he wishes */
  47346.     unsigned char *bufferPtr; /* Pointer to message buffer */
  47347.     unsigned char more; /* true more data will be written */
  47348. };
  47349.  
  47350. typedef struct PPCWriteParams PPCWriteParams;
  47351. typedef PPCWriteParams *PPCWriteParamsPtr;
  47352.  
  47353. æC 
  47354.  
  47355. æKY PPCReadParams
  47356. PPCReadParamsPtr
  47357. æFc PPCToolBox.h
  47358. æT struct
  47359. æD struct PPCReadParams {
  47360.      
  47361.     unsigned short resFiller; /* Must be set to zero */
  47362.     unsigned long sessRefNum; /* Session Identifier */
  47363.     unsigned long blockCreator; /* Message block creator */
  47364.     unsigned long blockType; /* Message block type */
  47365.     unsigned long bufferLength; /* Length of the message buffer */
  47366.     unsigned long actualLength; /* Actual Length Read */
  47367.     unsigned long userData; /* User can pass anything he wishes */
  47368.     unsigned char *bufferPtr; /* Pointer to message buffer */
  47369.     Boolean more; /* Is there more data to be read? */
  47370. };
  47371.  
  47372. typedef struct PPCReadParams PPCReadParams;
  47373. typedef PPCReadParams *PPCReadParamsPtr;
  47374.  
  47375. æC 
  47376.  
  47377. æKY PPCEndParams
  47378. PPCEndParamsPtr
  47379. æFc PPCToolBox.h
  47380. æT struct
  47381. æD struct PPCEndParams {
  47382.     PPCHeader 
  47383.     unsigned short resFiller; /* Must be set to zero */
  47384.     unsigned long sessRefNum; /* Session Identifier */
  47385. };
  47386.  
  47387. typedef struct PPCEndParams PPCEndParams;
  47388. typedef PPCEndParams *PPCEndParamsPtr;
  47389.  
  47390. æC 
  47391.  
  47392. æKY PPCCloseParams
  47393. PPCCloseParamsPtr
  47394. æFc PPCToolBox.h
  47395. æT struct
  47396. æD struct PPCCloseParams {
  47397.     PPCHeader 
  47398.     unsigned short portRefNum; /* Port Identifier*/
  47399. };
  47400.  
  47401. typedef struct PPCCloseParams PPCCloseParams;
  47402. typedef PPCCloseParams *PPCCloseParamsPtr;
  47403.  
  47404. æC 
  47405.  
  47406. æKY PortInfo
  47407. PortInfoPtr
  47408. æFc PPCToolBox.h
  47409. æT struct
  47410. æD struct PortInfo {
  47411.     unsigned short authRequired;
  47412.     PortName portName;
  47413. };
  47414.  
  47415. typedef struct PortInfo PortInfo;
  47416. typedef PortInfo *PortInfoPtr;
  47417.  
  47418. æC 
  47419.  
  47420. æKY IPCListPortParams
  47421. IPCListPortParamsPtr
  47422. æFc PPCToolBox.h
  47423. æT struct
  47424. æD struct IPCListPortParams {
  47425.     PPCHeader 
  47426.     unsigned short resFiller; /* Must be set to zero */
  47427.     unsigned short startIndex; /* Session Identifier */
  47428.     unsigned short requestCount; /* Message block creator */
  47429.     unsigned short actualCount; /* Message block type */
  47430.     PortNamePtr portName; /* Length of the message buffer */
  47431.     unsigned long portLocName; /* NBP or NAS type name to locate the Port Location */
  47432.     unsigned char *bufferPtr; /* Buffer Pointer */
  47433. };
  47434.  
  47435. typedef struct IPCListPortParams IPCListPortParams;
  47436. typedef IPCListPortParams *IPCListPortParamsPtr;
  47437.  
  47438. æC 
  47439.  
  47440. æKY PPCParamBlk
  47441. PPCParamBlkPtr
  47442. æFc PPCToolBox.h
  47443. æT struct
  47444. æD union PPCParamBlk {
  47445.     PPCOpenParams openPB;
  47446.     PPCInformParams informPB;
  47447.     PPCStartParams startPB;
  47448.     PPCAcceptParams acceptPB;
  47449.     PPCRejectParams rejectPB;
  47450.     PPCWriteParams writePB;
  47451.     PPCReadParams readPB;
  47452.     PPCEndParams endPB;
  47453.     PPCCloseParams closePB;
  47454.     IPCListPortParams listPB;
  47455. };
  47456.  
  47457. typedef union PPCParamBlk PPCParamBlk;
  47458.  
  47459. typedef PPCParamBlk *PPCParamBlkPtr;
  47460.  
  47461. æC 
  47462.  
  47463. æKY PPCInit
  47464. æFc PPCToolBox.h
  47465. æT Function
  47466. æD pascal OSErr PPCInit(void); 
  47467. æDT OSErr myVariable = PPCInit()(void);
  47468. æC 
  47469. Use the PPCInit function to initialize the PPC Toolbox.
  47470.  
  47471. After initialization, all PPC Toolbox routines can execute either synchronously
  47472. or asynchronously.
  47473.  
  47474. Result codes
  47475.  noErr            0  No error
  47476.  noglobalsErr  -904  PPC globals were not found (PPC is not loaded properly;   
  47477.  
  47478.                      don’t use PPC Toolbox)
  47479.  
  47480. æKY PPCOpen
  47481. æFc PPCToolBox.h
  47482. æT Function
  47483. æD pascal OSErr PPCOpen(PPCOpenParamsPtr PB,Boolean async); 
  47484. æDT OSErr myVariable = PPCOpen((PPCOpenParamsPtr) PB,(Boolean) async);
  47485. æC 
  47486. You open a port using the PPCOpen function, and you close a port using the
  47487. PPCClose function.
  47488.  
  47489. Use the PPCOpen function to open a new PPC port and to associate a name with it.
  47490.  
  47491. Parameter block
  47492.   Æ  12  cmdCompletion                long
  47493.   ¨  16  cmdResult                    word
  47494.   ¨  38  portRefNum                   word
  47495.   Æ  40  serviceType = {RealTime}     byte
  47496.   Æ  39  resFlag = {0}                byte
  47497.   Æ  42  networkVisible {TRUE/FALSE}  byte
  47498.   ¨  43  nbpRegistered {TRUE/FALSE}   byte
  47499.   Æ  44  name                         long
  47500.   Æ  48  location                     long
  47501.  
  47502. The portRefNum field returns the PPC port identifier. The serviceType field
  47503. indicates whether this port accepts sessions in real time.
  47504.  
  47505. The networkVisible field indicates whether the port should be made visible (both
  47506. for browsing as well as incoming requests). The nbpRegistered field indicates
  47507. that the port location specified was registered on the network. 
  47508.  
  47509. The name and location fields specify the name and location of the PPC port to be
  47510. opened.  The location field specifies the location of the port as an NBP name. 
  47511. If the location field is set to NIL, the PPC ToolBox name is used. Applications
  47512. are encouraged to use the default location, in which the port name is not
  47513. directly visible through NBP. You can obtain a list of port names using the
  47514. IPCListPorts function.
  47515.  
  47516.  
  47517. Result codes
  47518. noErr                   0  No error
  47519. notInitErr           -900  PPC was not initialized
  47520. portNameExistsErr    -910  Name is already registered
  47521. noPortTableErr       -911  Exceeding maximum number of ports
  47522. nameTypeErr          -902  Specified name type cannot be supported
  47523. localOnlyErr         -905  Port can only be used for local interprocess        
  47524.  
  47525.                            communication
  47526. paramErr                   A specified parameter is invalid
  47527. nbpDuplicate               Duplicate name already exists
  47528. badPortNameErr       -919  Port name is not valid
  47529. badLocNameErr        -931  Location name is not valid
  47530. badServiceMethodErr  -930  Service method requested is not supported
  47531.  
  47532. æKY PPCInform
  47533. æFc PPCToolBox.h
  47534. æT Function
  47535. æD pascal OSErr PPCInform(PPCInformParamsPtr PB,Boolean async); 
  47536. æDT OSErr myVariable = PPCInform((PPCInformParamsPtr) PB,(Boolean) async);
  47537. æC 
  47538. You use the PPCInform function to indicate that your application can receive
  47539. session requests. After you call PPCInform, your application can accept or
  47540. reject an incoming session request.
  47541.  
  47542. As long as a port has been opened, you can call the PPCInform function at any
  47543. time.
  47544.  
  47545. Parameter block
  47546.   Æ  12  cmdCompletion  long
  47547.   ¨  16  cmdResult      word
  47548.   Æ  38  portRefNum     word
  47549.   ¨  42  sessRefnum     long
  47550.   Æ  46  autoAccept     word
  47551.   ¨  48  serviceMethod  byte
  47552.   ¨  50  userData       long
  47553.   ¨  54  name           long
  47554.   ¨  58  userName       long
  47555.   ¨  62  location       long
  47556.  
  47557. You provide the PPC port identifier in the portRefNum field. A port identifier
  47558. is returned from a PPCOpen function. A session identifier is returned in the
  47559. sessRefNum field. This field is returned from a PPCStart, StartSecureSession, or
  47560. PPCInform function.
  47561.  
  47562. If you set the autoAccept flag, session requests are automatically accepted as
  47563. they are received.
  47564.  
  47565. The serviceMethod field indicates that this session request is in real time. The
  47566. userData field is the user data provided by the application that issues a start
  47567. command. This field is transparent to the PPC Toolbox. The user can send any
  47568. data in this field.
  47569.  
  47570. The name and location fields specify the port from which the session was
  47571. initiated. The userName field specifies the name of the user making the session
  47572. request, if authentication is required.
  47573.  
  47574. Apple Computer recommends that you execute the PPCInform function
  47575. asynchronously.
  47576.  
  47577. Result codes
  47578. noErr             0  No error
  47579. noPortErr      -903  Invalid PortRefNum
  47580. paramErr             Invalid parameter
  47581. portClosedErr  -916  Port is closed
  47582.  
  47583. æKY PPCStart
  47584. æFc PPCToolBox.h
  47585. æT Function
  47586. æD pascal OSErr PPCStart(PPCStartParamsPtr PB,Boolean async); 
  47587. æDT OSErr myVariable = PPCStart((PPCStartParamsPtr) PB,(Boolean) async);
  47588. æC 
  47589. You use the PPCStart or StartSecureSession function to initiate a session with
  47590. another port, and you use the PPCEnd function to end a session or close a
  47591. message.
  47592.  
  47593. Parameter block
  47594.  
  47595.   Æ   12  cmdCompletion  long
  47596.   ¨   16  cmdResult  word
  47597.   Æ   38  portRefNum  word
  47598.   ¨   38  sessRefNum  long
  47599.   ´   48  serviceMethod  byte
  47600.   Æ   46  userRefNum  word
  47601.   Æ   50  userData  long
  47602.   ¨   52  rejectInfo  long
  47603.   Æ   54  name  long
  47604.   Æ   62  location  long
  47605.  
  47606. You specify the PPC port identifier in the portRefNum field. The portRefNum is a
  47607. reference number for the port through which you are requesting a session. The
  47608. value you specify should correspond to the port reference number returned from
  47609. the PPCOpen function. 
  47610.  
  47611. The sessRefNum field returns a session identifier. You must set the
  47612. serviceMethod field to indicate that the session is to be connected in real
  47613. time. The userRefNum field specifies the user located at a particular port.
  47614.  
  47615. The initiating port can specify any information in the userData field. The
  47616. PPCInform function reports this data to the responding port upon its completion.
  47617.  
  47618. If a responding application rejects the session, it can specify an explanation
  47619. of the rejection in the rejectInfo field. This field contains a clientRejectErr
  47620. code.  If the PPC Toolbox rejects a session, this field returns a command result
  47621. of 0. Refer to the error code for an explanation of the failure.
  47622.  
  47623. The name and location fields specify the name and location of the PPC port to be
  47624. opened.  The location field specifies the location of the port as an NBP name. 
  47625. If the location is set to NIL, the PPC ToolBox name is used. Apple computer
  47626. recommends that you use the PPCBrowser function (instead of the IPCListPorts
  47627. function) to obtain the list of existing ports. You should also use the port
  47628. name and the location name returned by the PPCBrowser function to make
  47629. subsequent PPCStart and StartSecureSession calls.
  47630.  
  47631. The PPCStart function initiates a session with the destination port specified in
  47632. name and location fields.
  47633.  
  47634. Result codes  
  47635. noErr                   0   No error
  47636. notInitErr           -900  PPC was not initialized
  47637. noSessTableErr             Exceeding maximum number of sessions
  47638. nameTypeErr          -902  Specified name type cannot be supported
  47639. noUserNameErr        -913  userRefNum supplied does not correspond to a logged 
  47640.  
  47641.                            on user (or user name is not found in the usergroup
  47642.                            database at the server)
  47643. noPortErr            -903  Invalid portRefNum
  47644. userRejectErr        -912  Session request was rejected by the PPC Toolbox user
  47645. noResponseErr        -915  No response from the destination
  47646. noInformErr          -926  No inform is pending to accept or reject the start
  47647. authFailErr          -927  Authentication failure
  47648. badPortNameErr       -919  Port name is not valid
  47649. badLocNameErr        -931  Location name is not valid
  47650. badServiceMethodErr  -930  Service method requested is not supported
  47651. guestNotAllowedErr   -932  Guests are not allowed on this machine
  47652.  
  47653. æKY PPCReject
  47654. æFc PPCToolBox.h
  47655. æT Function
  47656. æD pascal OSErr PPCReject(PPCRejectParamsPtr PB,Boolean async); 
  47657. æDT OSErr myVariable = PPCReject((PPCRejectParamsPtr) PB,(Boolean) async);
  47658. æC 
  47659. The PPCReject function indicates that an application is not willing to accept a
  47660. particular session request. This is different from an application that rejects a
  47661. session request because a user is not successfully authenticated.
  47662.  
  47663. Parameter block
  47664.   Æ   12  cmdCompletion    long
  47665.   ¨   16  cmdResult        word
  47666.   Æ   38  sessRefNum       long
  47667.   Æ   42  rejectInfo       long
  47668.  
  47669. The sessRefNum field specifies a session identifier. A session reference number
  47670. is returned from a PPCStart, StartSecureSession, or PPCInform function. The
  47671. rejectInfo field is an optional field. The application receiving a session
  47672. request may specify any data in this field. The initiating application receives
  47673. this information.
  47674.  
  47675. Result codes
  47676. noErr             0  No error
  47677. notInitErr     -900  PPC was not initialized
  47678. noPortErr      -903  Invalid PortRefNum
  47679. portClosedErr  -916  Port is closed
  47680.  
  47681. æKY PPCWrite
  47682. æFc PPCToolBox.h
  47683. æT Function
  47684. æD pascal OSErr PPCWrite(PPCWriteParamsPtr PB,Boolean async); 
  47685. æDT OSErr myVariable = PPCWrite((PPCWriteParamsPtr) PB,(Boolean) async);
  47686. æC 
  47687. Parameter block
  47688.   Æ   12  cmdCompletion      long
  47689.   ¨   16  cmdResult          word
  47690.   Æ   38  sessRefNum         long
  47691.   Æ   42  blockCreator       long
  47692.   Æ   46  blockType          long
  47693.   Æ   50  bufferLength       long
  47694.   ¨   54  actualLength       long
  47695.   Æ   58  userData           long
  47696.   Æ   62  bufferPtr          long
  47697.   Æ   66  more               word
  47698.  
  47699. The sessRefNum field specifies a session identifier. A session reference number
  47700. is returned from a PPCStart, StartSecureSession, or PPCInform function. The
  47701. calling program uses the blockCreator and blockType fields to convey information
  47702. regarding the content of the block to the receiver. The PPCRead function passes
  47703. this information to the receiving program.
  47704.  
  47705. The bufferLength and bufferPtr fields specify the block to be sent. If the
  47706. result code is not noErr, actualLength returns the actual number of bytes sent.
  47707. The actualLength field returns the size of the block being read. The actual size
  47708. of the data block that was written is returned in the actualLength field.
  47709.  
  47710. The user can utilize the userData field. The data in this field contains can
  47711. deliver data to the application reading data. The more field is set to indicate
  47712. that additional data is being written. This field enables a user to construct
  47713. large message blocks. This field should be set to 0 to indicate the end of the
  47714. message block.
  47715.  
  47716. Apple Computer recommends that you execute the PPCWrite function asynchronously.
  47717.  
  47718. Result codes
  47719. noErr               0  No error
  47720. notInitErr       -900  PPC was not initialized
  47721. noPortErr        -903  Invalid PortRefNum
  47722. noSessionErr     -908  Invalid session identifier
  47723. sessClosedErr    -917  Session closed while writing
  47724.  
  47725. æKY PPCRead
  47726. æFc PPCToolBox.h
  47727. æT Function
  47728. æD pascal OSErr PPCRead(PPCReadParamsPtr PB,Boolean async); 
  47729. æDT OSErr myVariable = PPCRead((PPCReadParamsPtr) PB,(Boolean) async);
  47730. æC 
  47731. The PPCRead function reads incoming data from an application and the PPCWrite
  47732. function writes data to an application during a session.
  47733.  
  47734. Call the PPCRead function to read data blocks during a session.
  47735.  
  47736. Parameter block
  47737.   Æ   12  cmdCompletion     long
  47738.   ¨   16  cmdResult         word
  47739.   Æ   38  sessRefNum        long
  47740.   ¨   42  blockCreator      long
  47741.   ¨   46  blockType         long
  47742.   Æ   50  bufferLength      long
  47743.   ¨   54  actualLength      long
  47744.   ¨   58  userData          long
  47745.   Æ   62  bufferPtr         long
  47746.   ¨   66  more              word
  47747.  
  47748. The sessRefNum field specifies a session identifier. A session reference number
  47749. is returned from a PPCStart, StartSecureSession, or PPCInform function. The
  47750. blockCreator and blockType fields contain information regarding the contents of
  47751. the block read. The PPCWrite function specifies these parameters. The
  47752. bufferLength and bufferPtr fields specify a buffer to read the next block of
  47753. data. The actualLength field returns the size of the block being read. The
  47754. actual size of the data block being read is returned in the actualLength field.
  47755.  
  47756. The userData field is reserved for the application that transmits data. The
  47757. information it contains is delivered to the application reading data. This
  47758. userData field is transparent to the PPC Toolbox.
  47759.  
  47760. The more field is TRUE if the provided buffer cannot hold the entire PPC block.
  47761. The calling program makes iterations of the PPCRead calls to receive the entire
  47762. PPC block.
  47763.  
  47764. Apple Computer recommends that you execute the PPCRead function asynchronously.
  47765.  
  47766. Result codes
  47767. noErr             0  No error
  47768. notInitErr     -900  PPC was not initialized
  47769. noPortErr      -903  Invalid PortRefNum
  47770. noSessionErr   -908  Invalid session identifier
  47771. sessClosedErr  -917  Session closed while reading
  47772.  
  47773. Call the PPCRead function to read data blocks during a session.
  47774.  
  47775. æKY PPCEnd
  47776. æFc PPCToolBox.h
  47777. æT Function
  47778. æD pascal OSErr PPCEnd(PPCEndParamsPtr PB,Boolean async); 
  47779. æDT OSErr myVariable = PPCEnd((PPCEndParamsPtr) PB,(Boolean) async);
  47780. æC 
  47781. You should issue a PPCEnd function for each PPCStart and PPCAccept function, so
  47782. that network resources can be utilized by other applications.
  47783.  
  47784. Parameter block
  47785.   Æ   12  cmdCompletion  long
  47786.   ¨   16  cmdResult  word
  47787.   Æ   38  sessRefNum  long
  47788.  
  47789. You provide a session identifier in the sessRefNum fieldto identify the session
  47790. that you are terminating. The session reference number is returned from a
  47791. PPCStart, StartSecureSession, or PPCInform function.
  47792.  
  47793. Result codes
  47794. noErr            0  No error
  47795. notInitErr    -900  PPC was not initialized
  47796. noPortErr     -903  PortRefNum implied by the sessRefNum is invalid
  47797. noSessionErr  -908  Invalid session identifier
  47798.  
  47799. æKY PPCClose
  47800. æFc PPCToolBox.h
  47801. æT Function
  47802. æD pascal OSErr PPCClose(PPCCloseParamsPtr PB,Boolean async); 
  47803. æDT OSErr myVariable = PPCClose((PPCCloseParamsPtr) PB,(Boolean) async);
  47804. æC 
  47805. You use the PPCClose function to close the port specified by the port reference
  47806. number.
  47807.  
  47808. Parameter block
  47809.   Æ   12  cmdCompletion  long
  47810.   ¨   16  cmdResult  word
  47811.   Æ   38  portRefNum  word
  47812.  
  47813. The PPC port identifier is provided in the portRefNum field. This field is
  47814. returned from a PPCOpen function. 
  47815.  
  47816. Result codes
  47817. noErr                   0  No error
  47818. noPortErr            -903  Specified portRefNum is invalid
  47819. badPortNameErr       -919  Port name is not valid
  47820. badLocNameErr        -931  Location name is not valid
  47821. badServiceMethodErr  -930  Service method requested is not supported
  47822.  
  47823. æKY IPCListPorts
  47824. æFc PPCToolBox.h
  47825. æT Function
  47826. æD pascal OSErr IPCListPorts(IPCListPortsParamsPtr PB,Boolean async); 
  47827. æDT OSErr myVariable = IPCListPorts((IPCListPortsParamsPtr) PB,(Boolean) async);
  47828. æC 
  47829. You use the IPCListPorts function to list all available ports. The
  47830. ListPortParams data structure defines the parameter block used by the
  47831. IPCListPorts function.
  47832.  
  47833. Parameter block
  47834.   Æ   12  cmdCompletion  long
  47835.   ¨   16  cmdResult  word
  47836.   Æ   38  startIndex  word
  47837.   Æ   40  requestCount  word
  47838.   ¨   42  actualCount  word
  47839.   Æ   44  name  long
  47840.   Æ   48  location  long
  47841.   Æ   52  bufferPtr  long
  47842.  
  47843. The startIndex field specifies the index to the port entry list from which the
  47844. PPC Toolbox begins to get the list. Set the startIndex field to begin at 0. The
  47845. requestCount field tells the number of port names requested.
  47846.  
  47847. The actualCount field returns the actual number of entries read. The calling
  47848. program can make iteration of the IPCListPorts function to get the entire list
  47849. of the port names. Ports that are not network visible to the network are not
  47850. included in the ports listing.
  47851.  
  47852. You can specify particular values for the name field or you can use
  47853. metacharacters. You can specify an equal sign (=) for both nameStr and typeStr
  47854. fields for the port name to get a list of all the port names at that location.
  47855. If the location field is set to NIL, the PPC Toolbox returns the port names of
  47856. the local machine only.
  47857.  
  47858. IPCListPorts returns the port names in the area of memory pointed to by
  47859. bufferPtr, and it specifies each port name in a PortInfo data structure.
  47860.  
  47861. Result codes
  47862. noErr               0  No error
  47863. noInitErr              PPC Toolbox was not initialized
  47864. noSessTableErr         Exceeding maximum number of sessions
  47865. nameTypeErr      -902  Specified name type cannot be supported
  47866. noUserNameErr    -913  A user name was not found
  47867. rejectErr              Session request was rejected
  47868. noResponseErr    -915  No response from the destination
  47869. noSessErr              Session was aborted
  47870. badPortNameErr   -919  Port name is not valid
  47871. badLocNameErr    -931  Location name is not valid
  47872.  
  47873. æKY PromptForUserIdentity
  47874. æFc PPCToolBox.h
  47875. æT Function
  47876. æD pascal OSErr PromptForUserIdentity(unsigned short *userRef,StringPtr userName,
  47877.     Boolean *guestSelected,Boolean allowGuest,StringPtr prompt); 
  47878. æDT OSErr myVariable = PromptForUserIdentity((unsigned short *) userRef,(StringPtr) userName,(
  47879.     Boolean) * guestSelected,(Boolean) allowGuest,(StringPtr) prompt);
  47880. æC 
  47881.  
  47882. æKY DeleteUserIdentity
  47883. æFc PPCToolBox.h
  47884. æT Function
  47885. æD pascal OSErr DeleteUserIdentity(unsigned short userRef); 
  47886. æDT OSErr myVariable = DeleteUserIdentity((unsigned short) userRef);
  47887. æC
  47888. Use the DeleteUserIdentity function to remove a user.
  47889.  
  47890.  
  47891. The DeleteUserIdentity function removes the name and the corresponding password
  47892. entry for the invalidated user.
  47893.  
  47894. Result codes
  47895. noUserRefNum    User reference number does not exist
  47896.  
  47897.  
  47898. æKY GetDefaultUser
  47899. æFc PPCToolBox.h
  47900. æT Function
  47901. æD pascal OSErr GetDefaultUser(unsigned short *userRef,StringPtr userName); 
  47902. æDT OSErr myVariable = GetDefaultUser((unsigned short *) userRef,(StringPtr) userName);
  47903. æC 
  47904. The GetDefaultUser function returns the name and the user reference number of
  47905. the default user.
  47906.  
  47907. Result codes
  47908. noDefaultUser    Default user does not exist
  47909.  
  47910. æKY StartSecureSession
  47911. æFc PPCToolBox.h
  47912. æT Function
  47913. æD pascal OSErr StartSecureSession(PPCStartParams *startPB,StringPtr userName,
  47914.     Boolean UseDefault,Boolean allowGuest,Boolean *guestSelected,StringPtr prompt); 
  47915. æDT OSErr myVariable = StartSecureSession((PPCStartParams *) startPB,(StringPtr) userName,()
  47916.     Boolean UseDefault,(Boolean) allowGuest,(Boolean *) guestSelected,(StringPtr) prompt);
  47917. æC 
  47918. The StartSecureSession function provides authentication services to identify
  47919. each user who requests a session. This function combines the functions of
  47920. prompting for user name, password, and PPCStart into one synchronous procedure
  47921. call. Use the StartSecureSession function when a port destination requires
  47922. authentication.
  47923.  
  47924.  
  47925. Your program fills out a parameter block just as though it were calling the
  47926. PPCStart function.
  47927.  
  47928. æKY PPCBrowser
  47929. æFc PPCToolBox.h
  47930. æT Function
  47931. æTN A82B
  47932. æD pascal OSErr PPCBrowser(const Str255 prompt,const Str255 applListLabel,
  47933.     Boolean defaultSpecified,LocName *theLoc,PortInfo *thePortInfo,ProcPtr portFilter)
  47934.     = {0x303C,0x0B00,0xA82B}; 
  47935. æDT OSErr myVariable = PPCBrowser((const Str255) prompt,(const Str255) applListLabel,()
  47936.     Boolean defaultSpecified,(LocName *) theLoc,(PortInfo *) thePortInfo,(ProcPtr) portFilter);
  47937. æC 
  47938. To enable the user to display available ports, use the PPCBrowser function.
  47939.  
  47940. The prompt parameter is a line of text displayed as a prompt in the browse
  47941. dialog box.
  47942.  
  47943. The portListTitle parameter is used as the title of the list of PPC ports. If
  47944. this field is NIL or empty, the default title is used (currently “PPC Ports”).
  47945.  
  47946. If the defaultSpecified parameter is TRUE, the browser tries to select the PPC
  47947. port specified by the theLoc and the thePort parameters as the browser first
  47948. appears. If the PPCBrowser function returns noErr, the PPC port name of the
  47949. chosen port is returned in the thePort parameter.
  47950.  
  47951. The portFilter parameter determines how the list of PPC ports is filtered. If
  47952. this parameter is NIL, the names of all existing PPC ports is returned by the
  47953. IPCListPorts function is displayed. If this parameter isn’t NIL, it must be a
  47954. pointer to the MyPortFilter function.
  47955.  
  47956. FUNCTION MyPortFilter (theLoc: LocName; thePort: PortName) : OSErr; 
  47957.  
  47958. The MyPortFilter function is called once for each port returned by the
  47959. IPCListPorts function before a port is added to the dialog list. This function
  47960. should return TRUE for each port that should be displayed in the browser, and
  47961. FALSE for each port that shouldn’t be displayed.
  47962.  
  47963. If the PPCBrowser function returns noErr, theLoc and thePort parameters specify
  47964. the port chosen by the user. If the PPCBrowser returns userCanceledErr, the user
  47965. hit the Cancel button, and no port was selected.
  47966.  
  47967.  
  47968. æKY Printing.h
  47969. æKL PrClose
  47970. PrCloseDoc
  47971. PrClosePage
  47972. PrCtlCall
  47973. PrDlgMain
  47974. PrDrvrClose
  47975. PrDrvrDCE
  47976. PrDrvrOpen
  47977. PrDrvrVers
  47978. PrError
  47979. PrGeneral
  47980. PrintDefault
  47981. PrJobDialog
  47982. PrJobInit
  47983. PrJobMerge
  47984. PrNoPurge
  47985. PrOpen
  47986. PrOpenDoc
  47987. PrOpenPage
  47988. PrPicFile
  47989. PrPurge
  47990. PrSetError
  47991. PrStlDialog
  47992. PrStlInit
  47993. PrValidate
  47994.  
  47995. bDraftLoop
  47996. bSpoolLoop
  47997. bUser1Loop
  47998. bUser2Loop
  47999. draftBitsOp
  48000. feedCut
  48001. feedFanfold
  48002. feedMechCut
  48003. feedOther
  48004. getRotnOp
  48005. getRslDataOp
  48006. iFMgrCtl
  48007. iIOAbort
  48008. iMemFullErr
  48009. iPFMaxPgs
  48010. iPrAbort
  48011. iPrBitsCtl
  48012. iPrDevCtl
  48013. iPrDrvrRef
  48014. iPrEvtCtl
  48015. iPrIOCtl
  48016. iPrPgFract
  48017. iPrPgFst
  48018. iPrPgMax
  48019. iPrRelease
  48020. iPrSavPFil
  48021. lHiPaintBits
  48022. lHiScreenBits
  48023. lPaintBits
  48024. lPrDocClose
  48025. lPrDocOpen
  48026. lPrEvtAll
  48027. lPrEvtTop
  48028. lPrLFSixth
  48029. lPrLFStd
  48030. lPrLineFeed
  48031. lPrPageClose
  48032. lPrPageEnd
  48033. lPrPageOpen
  48034. lPrReset
  48035. lScreenBits
  48036. noDraftBitsOp
  48037. NoSuchRsl
  48038. PItemProcPtr
  48039. pPrGlobals
  48040. PrIdleProcPtr
  48041. RgType1
  48042. scanBT
  48043. scanLR
  48044. scanRL
  48045. scanTB
  48046. setRslOp
  48047. sPrDrvr
  48048. TDftBitsBlk
  48049. TFeed
  48050. TGetRotnBlk
  48051. TGetRslBlk
  48052. TGnlData
  48053. THPfPgDir
  48054. THPrint
  48055. TPfPgDir
  48056. TPPfPgDir
  48057. TPPrDlg
  48058. TPPrInfo
  48059. TPPrint
  48060. TPPrJob
  48061. TPPrPort
  48062. TPPrStatus
  48063. TPPrStl
  48064. TPPrXInfo
  48065. TPrDlg
  48066. TPRect
  48067. TPrInfo
  48068. TPrint
  48069. TPrJob
  48070. TPrPort
  48071. TPrStatus
  48072. TPrStl
  48073. TPrXInfo
  48074. TRslRec
  48075. TRslRg
  48076. TScan
  48077. TSetRslBlk
  48078.  
  48079. æKY iPFMaxPgs
  48080. æFc Printing.h
  48081. æT #define
  48082. æD #define iPFMaxPgs 128
  48083. æC 
  48084.  
  48085. æKY iPrPgFract
  48086. æFc Printing.h
  48087. æT #define
  48088. æD #define iPrPgFract 120 /*Page scale factor. ptPgSize (below) is in units of 1/iPrPgFract*/
  48089. æC 
  48090.  
  48091. æKY iPrPgFst
  48092. æFc Printing.h
  48093. æT #define
  48094. æD #define iPrPgFst 1 /*Page range constants*/
  48095. æC 
  48096.  
  48097. æKY iPrPgMax
  48098. æFc Printing.h
  48099. æT #define
  48100. æD #define iPrPgMax 9999
  48101. æC 
  48102.  
  48103. æKY iPrRelease
  48104. æFc Printing.h
  48105. æT #define
  48106. æD #define iPrRelease 3 /*Current version number of the code.*/
  48107. æC 
  48108.  
  48109. æKY iPrSavPFil
  48110. æFc Printing.h
  48111. æT #define
  48112. æD #define iPrSavPFil -1
  48113. æC 
  48114.   /* The following result codes are LaserWriter-specific */
  48115.  
  48116.                   –4101;   /* Printer not found or closed */
  48117.                   –4100;   /* Connection just closed */
  48118.                   –4099;   /* Write request too big */
  48119.                   –4098;   /* Request already active */
  48120.                   –4097;   /* Bad connection refnum */
  48121.                   –4096;   /* No free CCBs (Connect Control Blocks) available */
  48122.                   –8133;   /* PostScript error occurred during transmission */
  48123.                            /* of data to printer. Most often caused by a bug */
  48124.                            /* in the PostScript code being downloaded. */
  48125.                   –8132;   /* Timeout occured. This error is returned when */
  48126.                            /* no data has been sent to the printer for 2 */
  48127.                            /* minutes. Usually caused by extremely long */
  48128.                            /* imaging times. */
  48129.  
  48130. æKY iPrAbort
  48131. æFc Printing.h
  48132. æT #define
  48133. æD #define iPrAbort 0x0080
  48134. æC 
  48135.  
  48136. æKY iPrDevCtl
  48137. æFc Printing.h
  48138. æT #define
  48139. æD #define iPrDevCtl 7 /*The PrDevCtl Proc's ctl number*/
  48140. æC 
  48141.  
  48142. æKY lPrReset
  48143. æFc Printing.h
  48144. æT #define
  48145. æD #define lPrReset 0x00010000 /*The PrDevCtl Proc's CParam for reset*/
  48146. æC 
  48147.  
  48148. æKY lPrLineFeed
  48149. æFc Printing.h
  48150. æT #define
  48151. æD #define lPrLineFeed 0x00030000
  48152. æC 
  48153.  
  48154. æKY lPrLFStd
  48155. æFc Printing.h
  48156. æT #define
  48157. æD #define lPrLFStd 0x0003FFFF /*The PrDevCtl Proc's CParam for std paper advance*/
  48158. æC 
  48159.  
  48160. æKY lPrLFSixth
  48161. æFc Printing.h
  48162. æT #define
  48163. æD #define lPrLFSixth 0x0003FFFF
  48164. æC 
  48165.  
  48166. æKY lPrPageEnd
  48167. æFc Printing.h
  48168. æT #define
  48169. æD #define lPrPageEnd 0x00020000 /*The PrDevCtl Proc's CParam for end page*/
  48170. æC 
  48171.  
  48172. æKY lPrDocOpen
  48173. æFc Printing.h
  48174. æT #define
  48175. æD #define lPrDocOpen 0x00010000
  48176. æC 
  48177.  
  48178. æKY lPrPageOpen
  48179. æFc Printing.h
  48180. æT #define
  48181. æD #define lPrPageOpen 0x00040000
  48182. æC 
  48183.  
  48184. æKY lPrPageClose
  48185. æFc Printing.h
  48186. æT #define
  48187. æD #define lPrPageClose 0x00020000
  48188. æC 
  48189.  
  48190. æKY lPrDocClose
  48191. æFc Printing.h
  48192. æT #define
  48193. æD #define lPrDocClose 0x00050000
  48194. æC 
  48195.  
  48196. æKY iFMgrCtl
  48197. æFc Printing.h
  48198. æT #define
  48199. æD #define iFMgrCtl 8 /*The FMgr's Tail-hook Proc's ctl number*/
  48200. æC 
  48201.  
  48202. æKY iMemFullErr
  48203. æFc Printing.h
  48204. æT #define
  48205. æD #define iMemFullErr -108
  48206. æC 
  48207.  
  48208. æKY iIOAbort
  48209. æFc Printing.h
  48210. æT #define
  48211. æD #define iIOAbort -27
  48212. æC 
  48213.  
  48214. æKY pPrGlobals
  48215. æFc Printing.h
  48216. æT #define
  48217. æD #define pPrGlobals 0x00000944 /*The PrVars lo mem area:*/
  48218. æC 
  48219.  
  48220. æKY bDraftLoop
  48221. æFc Printing.h
  48222. æT #define
  48223. æD #define bDraftLoop 0
  48224. æC 
  48225.  
  48226. æKY bSpoolLoop
  48227. æFc Printing.h
  48228. æT #define
  48229. æD #define bSpoolLoop 1
  48230. æC 
  48231.  
  48232. æKY bUser1Loop
  48233. æFc Printing.h
  48234. æT #define
  48235. æD #define bUser1Loop 2
  48236. æC 
  48237.  
  48238. æKY bUser2Loop
  48239. æFc Printing.h
  48240. æT #define
  48241. æD #define bUser2Loop 3
  48242. æC 
  48243.  
  48244. æKY iPrBitsCtl
  48245. æFc Printing.h
  48246. æT #define
  48247. æD #define iPrBitsCtl 4
  48248. æC 
  48249.  
  48250. æKY lScreenBits
  48251. æFc Printing.h
  48252. æT #define
  48253. æD #define lScreenBits 0
  48254. æC 
  48255.  
  48256. æKY lPaintBits
  48257. æFc Printing.h
  48258. æT #define
  48259. æD #define lPaintBits 1
  48260. æC 
  48261.  
  48262. æKY lHiScreenBits
  48263. æFc Printing.h
  48264. æT #define
  48265. æD #define lHiScreenBits 0x00000002 /*The Bitmap Print Proc's Screen Bitmap param*/
  48266. æC 
  48267.  
  48268. æKY lHiPaintBits
  48269. æFc Printing.h
  48270. æT #define
  48271. æD #define lHiPaintBits 0x00000003 /*The Bitmap Print Proc's Paint [sq pix] param*/
  48272. æC 
  48273.  
  48274. æKY iPrIOCtl
  48275. æFc Printing.h
  48276. æT #define
  48277. æD #define iPrIOCtl 5
  48278. æC 
  48279.  
  48280. æKY iPrEvtCtl
  48281. æFc Printing.h
  48282. æT #define
  48283. æD #define iPrEvtCtl 6 /*The PrEvent Proc's ctl number*/
  48284. æC 
  48285.  
  48286. æKY lPrEvtAll
  48287. æFc Printing.h
  48288. æT #define
  48289. æD #define lPrEvtAll 0x0002FFFD /*The PrEvent Proc's CParam for the entire screen*/
  48290. æC 
  48291.  
  48292. æKY lPrEvtTop
  48293. æFc Printing.h
  48294. æT #define
  48295. æD #define lPrEvtTop 0x0001FFFD /*The PrEvent Proc's CParam for the top folder*/
  48296. æC 
  48297.  
  48298. æKY sPrDrvr
  48299. æFc Printing.h
  48300. æT #define
  48301. æD #define sPrDrvr ".Print"
  48302. æC 
  48303.  
  48304. æKY iPrDrvrRef
  48305. æFc Printing.h
  48306. æT #define
  48307. æD #define iPrDrvrRef -3
  48308. æC 
  48309.  
  48310. æKY getRslDataOp
  48311. æFc Printing.h
  48312. æT #define
  48313. æD #define getRslDataOp 4
  48314. æC 
  48315.  
  48316. æKY setRslOp
  48317. æFc Printing.h
  48318. æT #define
  48319. æD #define setRslOp 5
  48320. æC 
  48321.  
  48322. æKY draftBitsOp
  48323. æFc Printing.h
  48324. æT #define
  48325. æD #define draftBitsOp 6
  48326. æC 
  48327.  
  48328. æKY noDraftBitsOp
  48329. æFc Printing.h
  48330. æT #define
  48331. æD #define noDraftBitsOp 7
  48332. æC 
  48333.  
  48334. æKY getRotnOp
  48335. æFc Printing.h
  48336. æT #define
  48337. æD #define getRotnOp 8
  48338. æC 
  48339.  
  48340. æKY NoSuchRsl
  48341. æFc Printing.h
  48342. æT #define
  48343. æD #define NoSuchRsl 1
  48344. æC 
  48345.  
  48346. æKY RgType1
  48347. æFc Printing.h
  48348. æT #define
  48349. æD #define RgType1 1
  48350. æC 
  48351.  
  48352. æKY TFeed
  48353. feedCut
  48354. feedFanfold
  48355. feedMechCut
  48356. feedOther
  48357. æFc Printing.h
  48358. æT enum
  48359. æD enum {feedCut,feedFanfold,feedMechCut,feedOther};
  48360. typedef unsigned char TFeed;
  48361. æC 
  48362.  
  48363. æKY TScan
  48364. scanTB
  48365. scanBT
  48366. scanLR
  48367. scanRL
  48368. æFc Printing.h
  48369. æT enum
  48370. æD enum {scanTB,scanBT,scanLR,scanRL};
  48371. typedef unsigned char TScan;
  48372. æC 
  48373.  
  48374. æKY TPRect
  48375. æFc Printing.h
  48376. æT typedef
  48377. æD typedef Rect *TPRect;
  48378. æC 
  48379.  
  48380. æKY PrIdleProcPtr
  48381. æFc Printing.h
  48382. æT typedef
  48383. æD typedef pascal void (*PrIdleProcPtr)(void);
  48384. æC 
  48385.  
  48386. æKY PItemProcPtr
  48387. æFc Printing.h
  48388. æT typedef
  48389. æD typedef pascal void (*PItemProcPtr)(DialogPtr theDialog, short item);
  48390. æC 
  48391.  
  48392. æKY TPrPort
  48393. TPPrPort
  48394. æFc Printing.h
  48395. æT struct
  48396. æD struct TPrPort {
  48397.     GrafPort gPort; /*The Printer's graf port.*/
  48398.     QDProcs gProcs; /*..and its procs*/
  48399.     long lGParam1; /*16 bytes for private parameter storage.*/
  48400.     long lGParam2;
  48401.     long lGParam3;
  48402.     long lGParam4;
  48403.     Boolean fOurPtr; /*Whether the PrPort allocation was done by us.*/
  48404.     Boolean fOurBits; /*Whether the BitMap allocation was done by us.*/
  48405. };
  48406.  
  48407. typedef struct TPrPort TPrPort;
  48408. typedef TPrPort *TPPrPort;
  48409.  
  48410. /* Printing Graf Port. All printer imaging, whether spooling, banding, etc, happens "thru" a GrafPort.
  48411. This is the "PrPeek" record. */
  48412. æC 
  48413.  
  48414. æKY TPrInfo
  48415. TPPrInfo
  48416. æFc Printing.h
  48417. æT struct
  48418. æD struct TPrInfo {
  48419.     short iDev; /*Font mgr/QuickDraw device code*/
  48420.     short iVRes; /*Resolution of device, in device coordinates*/
  48421.     short iHRes; /*..note: V before H => compatable with Point.*/
  48422.     Rect rPage; /*The page (printable) rectangle in device coordinates.*/
  48423. };
  48424.  
  48425. typedef struct TPrInfo TPrInfo;
  48426. typedef TPrInfo *TPPrInfo;
  48427.  
  48428. /* Print Info Record: The parameters needed for page composition. */
  48429. æC 
  48430. »The Printer Information Subrecord
  48431.  
  48432. The printer information subrecord (field prInfo of the print record) gives you the
  48433. information needed for page composition. It’s defined as follows:
  48434.  
  48435. TYPE  TPrInfo = RECORD
  48436.                   iDev:   INTEGER;  {used internally}
  48437.                   iVRes:  INTEGER;  {vertical resolution of printer}
  48438.                   iHRes:  INTEGER;  {horizontal resolution of printer}
  48439.                   rPage:  Rect      {page rectangle}
  48440.                 END;
  48441.  
  48442. RPage is the page rectangle, representing the boundaries of the printable page:  The
  48443. printing grafPort’s boundary rectangle, portRect, and clipRgn are set to this rectangle.
  48444. Its top left corner always has coordinates (0,0); the coordinates of the bottom right
  48445. corner give the maximum page height and width attainable on the given printer, in
  48446. dots. Typically these are slightly less than the physical dimensions of the paper,
  48447. because of the printer’s mechanical limitations. RPage is set as a result of the
  48448. style dialog.
  48449.  
  48450. The rPage rectangle is inside the paper rectangle, specified by the rPaper field of
  48451. the print record. RPaper gives the physical paper size, defined in the same coordinate
  48452. system as rPage (see Figure 4). Thus the top left coordinates of the paper rectangle
  48453. are typically negative and its bottom right coordinates are greater than those of the
  48454. page rectangle.
  48455.  
  48456. IVRes and iHRes give the printer’s vertical and horizontal resolution in dots per
  48457. inch. Thus, if you divide the width of rPage by iHRes, you get the width of the page
  48458. rectangle in inches.
  48459.  
  48460. æKY TPrStl
  48461. TPPrStl
  48462. æFc Printing.h
  48463. æT struct
  48464. æD struct TPrStl {
  48465.     short wDev;
  48466.     short iPageV;
  48467.     short iPageH;
  48468.     char bPort;
  48469.     TFeed feed;
  48470. };
  48471.  
  48472. typedef struct TPrStl TPrStl;
  48473. typedef TPrStl *TPPrStl;
  48474.  
  48475. æC 
  48476. »Additional Device Information
  48477.  
  48478. The prStl and prXInfo fields of the print record provide device information that your
  48479. application may need to refer to.
  48480.  
  48481. The prStl field of the print record is defined as follows:
  48482.  
  48483. TYPE TPrStl = RECORD
  48484.                 wDev:  INTEGER;  {high byte specifies device}
  48485.                 {more fields for internal use}
  48486.               END;
  48487.  
  48488. The high-order byte of the wDev field indicates which printer is currently selected. 
  48489. A value of 0 indicates the Macintosh screen; other values are reserved for future
  48490. use. The low-order byte of wDev is used internally.
  48491.  
  48492. æKY TPrXInfo
  48493. TPPrXInfo
  48494. æFc Printing.h
  48495. æT struct
  48496. æD struct TPrXInfo {
  48497.     short iRowBytes;
  48498.     short iBandV;
  48499.     short iBandH;
  48500.     short iDevBytes;
  48501.     short iBands;
  48502.     char bPatScale;
  48503.     char bUlThick;
  48504.     char bUlOffset;
  48505.     char bUlShadow;
  48506.     TScan scan;
  48507.     char bXInfoX;
  48508. };
  48509.  
  48510. typedef struct TPrXInfo TPrXInfo;
  48511. typedef TPrXInfo *TPPrXInfo;
  48512.  
  48513. æC 
  48514. The prXInfo field of the print record is defined as follows:
  48515.  
  48516. TYPE  TPrXInfo = RECORD
  48517.                    iRowBytes:  INTEGER;  {used internally}
  48518.                    iBandV:     INTEGER;  {used internally}
  48519.                    iBandH:     INTEGER;  {used internally}
  48520.                    iDevBytes:  INTEGER;  {size of buffer}
  48521.                    {more fields for internal use}
  48522.                  END;
  48523.  
  48524. IDevBytes is the number of bytes of memory required as a buffer for spool printing.
  48525. (You need this information only if you choose to allocate your own buffer.)
  48526.  
  48527. æKY TPrJob
  48528. TPPrJob
  48529. æFc Printing.h
  48530. æT struct
  48531. æD struct TPrJob {
  48532.     short iFstPage; /*Page Range.*/
  48533.     short iLstPage;
  48534.     short iCopies; /*No. copies.*/
  48535.     char bJDocLoop; /*The Doc style: Draft, Spool, .., and ..*/
  48536.     Boolean fFromUsr; /*Printing from an User's App (not PrApp) flag*/
  48537.     PrIdleProcPtr pIdleProc; /*The Proc called while waiting on IO etc.*/
  48538.     StringPtr pFileName; /*Spool File Name: NIL for default.*/
  48539.     short iFileVol; /*Spool File vol, set to 0 initially*/
  48540.     char bFileVers; /*Spool File version, set to 0 initially*/
  48541.     char bJobX; /*An eXtra byte.*/
  48542. };
  48543.  
  48544. typedef struct TPrJob TPrJob;
  48545. typedef TPrJob *TPPrJob;
  48546.  
  48547. /* Print Job: Print "form" for a single print request. */
  48548. æC 
  48549. »The Job Subrecord
  48550.  
  48551. The job subrecord (field prJob of the print record) contains information about a
  48552. particular printing job. Its contents are set as a result of the job dialog.
  48553.  
  48554. •••Refer to Figure 4.•••
  48555.  
  48556. Figure 4–Page and Paper Rectangles
  48557.  
  48558. The job subrecord is defined as follows:
  48559.  
  48560. TYPE TPrJob = RECORD
  48561.                 iFstPage:   INTEGER;     {first page to print}
  48562.                 iLstPage:   INTEGER;     {last page to print}
  48563.                 iCopies:    INTEGER;     {number of copies}
  48564.                 bJDocLoop:  SignedByte;  {printing method}
  48565.                 fFromUsr:   BOOLEAN;     {used internally}
  48566.                 pIdleProc:  ProcPtr;     {background procedure}
  48567.                 pFileName:  StringPtr;   {spool file name}
  48568.                 iFileVol:   INTEGER;     {spool file volume reference number}
  48569.                 bFileVers:  SignedByte;  {spool file version number}
  48570.                 bJobX:      SignedByte   {used internally}
  48571.               END;
  48572.  
  48573. BJDocLoop designates the printing method that the Printing Manager will use. It will
  48574. be one of the following predefined constants:
  48575.  
  48576. CONST  bDraftLoop = 0;    {draft printing}
  48577.        bSpoolLoop = 1;    {spool printing}
  48578.  
  48579. Draft printing means that the document will be printed immediately. Spool printing
  48580. means that printing may be deferred:  The Printing Manager writes out a representation
  48581. of the document’s printed image to a disk file (or possibly to memory); this information
  48582. is then converted into a bit image and printed. For details about the printing methods,
  48583. see the “Methods of Printing” section below. The Printing Manager sets the bJDocLoop
  48584. field; your application should not change it.
  48585.  
  48586. IFstPage and iLstPage designate the first and last pages to be printed. These page
  48587. numbers are relative to the first page counted by the Printing Manager. The Printing
  48588. Manager knows nothing about any page numbering placed by an application within a
  48589. document.
  48590.  
  48591. ICopies is the number of copies to print. The Printing Manager automatically handles
  48592. multiple copies for spool printing or for printing on the LaserWriter. Your application
  48593. only needs this number for draft printing on the Imagewriter.
  48594.  
  48595. PIdleProc is a pointer to the background procedure (explained below) for this printing
  48596. operation. In a newly initialized print record this field is set to NIL, designating
  48597. the default background procedure, which just polls the keyboard and cancels further
  48598. printing if the user types Command-period. You can install a background procedure of
  48599. your own by storing a pointer to your procedure directly into the pIdleProc field.
  48600.  
  48601. For spool printing, your application may optionally provide a spool file name, volume
  48602. reference number, and version number (described in the File Manager chapter):
  48603.  
  48604.   •  PFileName is the name of the spool file. This field is initialized to
  48605.      NIL, and generally not changed by the application. NIL denotes the
  48606.      default file name (normally 'Print File') stored in the printer resource
  48607.      file.
  48608.   •  IFileVol is the volume reference number of the spool file. This field
  48609.      is initialized to 0, representing the default volume. You can use the
  48610.      File Manager function SetVol to change the default volume, or you can
  48611.      override the default setting by storing directly into this field.
  48612.   •  BFileVers is the version number of the spool file, initialized to 0.
  48613.  
  48614. æKY TPrint
  48615. TPPrint
  48616. THPrint
  48617. æFc Printing.h
  48618. æT struct
  48619. æD struct TPrint {
  48620.     short iPrVersion; /*(2) Printing software version*/
  48621.     TPrInfo prInfo; /*(14) the PrInfo data associated with the current style.*/
  48622.     Rect rPaper; /*(8) The paper rectangle [offset from rPage]*/
  48623.     TPrStl prStl; /*(8)  This print request's style.*/
  48624.     TPrInfo prInfoPT; /*(14)  Print Time Imaging metrics*/
  48625.     TPrXInfo prXInfo; /*(16)  Print-time (expanded) Print info record.*/
  48626.     TPrJob prJob; /*(20) The Print Job request (82)  Total of the above; 120-82 = 38 bytes needed to fill 120*/
  48627.     short printX[19]; /*Spare to fill to 120 bytes!*/
  48628. };
  48629.  
  48630. typedef struct TPrint TPrint;
  48631. typedef TPrint *TPPrint, **THPrint;
  48632.  
  48633. /* The universal 120 byte printing record */
  48634. æC 
  48635. Print records are referred to by handles. Their structure is as follows:
  48636.  
  48637. TYPE  THPrint = ^TPPrint;
  48638.       TPPrint = ^TPrint;
  48639.       TPrint  = RECORD
  48640.                    iPrVersion:  INTEGER;  {Printing Manager version}
  48641.                    prInfo:      TPrInfo;  {printer information subrecord}
  48642.                    rPaper:      Rect;     {paper rectangle}
  48643.                    prStl:       TPrStl;   {additional device information}
  48644.                    prInfoPT:    TPrInfo;  {used internally}
  48645.                    prXInfo:     TPrXInfo; {additional device information}
  48646.                    prJob:       TPrJob;   {job subrecord}
  48647.                    printX:      ARRAY[1..19] OF INTEGER {not used}
  48648.                  END;
  48649.  
  48650. Warning:  Your application should not change the data in the print record—be
  48651.           sure to use the standard dialogs for setting this information. The
  48652.           only fields you’ll need to set directly are some containing optional
  48653.           information in the job subrecord (explained below). Attempting to set
  48654.           other values directly in the print record can produce unexpected
  48655.          results.
  48656.  
  48657. IPrVersion identifies the version of the Printing Manager that initialized this print
  48658. record. If you try to use a print record that’s invalid for the current version of
  48659. the Printing Manager or for the currently installed printer, the Printing Manager
  48660. will correct the record by filling it with default values.
  48661.  
  48662. The other fields of the print record are discussed in separate sections below.
  48663.  
  48664. Note:  Whenever you save a document, you should write an appropriate print
  48665.        record in the document’s resource file. This lets the document
  48666.        “remember” its own printing parameters for use the next time it’s
  48667.        printed.
  48668.  
  48669. æKY TPrStatus
  48670. TPPrStatus
  48671. æFc Printing.h
  48672. æT struct
  48673. æD struct TPrStatus {
  48674.     short iTotPages; /*Total pages in Print File.*/
  48675.     short iCurPage; /*Current page number*/
  48676.     short iTotCopies; /*Total copies requested*/
  48677.     short iCurCopy; /*Current copy number*/
  48678.     short iTotBands; /*Total bands per page.*/
  48679.     short iCurBand; /*Current band number*/
  48680.     Boolean fPgDirty; /*True if current page has been written to.*/
  48681.     Boolean fImaging; /*Set while in band's DrawPic call.*/
  48682.     THPrint hPrint; /*Handle to the active Printer record*/
  48683.     TPPrPort pPrPort; /*Ptr to the active PrPort*/
  48684.     PicHandle hPic; /*Handle to the active Picture*/
  48685. };
  48686.  
  48687. typedef struct TPrStatus TPrStatus;
  48688. typedef TPrStatus *TPPrStatus;
  48689.  
  48690. /* Print Status: Print information during printing. */
  48691. æC 
  48692. The prStatus parameter is a printer status record that PrPicFile will use to report
  48693. on its progress:
  48694.  
  48695. TYPE  TPrStatus = RECORD
  48696.                     iTotPages:   INTEGER;    {number of pages in spool file}
  48697.                     iCurPage:    INTEGER;    {page being printed}
  48698.                     iTotCopies:  INTEGER;    {number of copies requested}
  48699.                     iCurCopy:    INTEGER;    {copy being printed}
  48700.                     iTotBands:   INTEGER;    {used internally}
  48701.                     iCurBand:    INTEGER;    {used internally}
  48702.                     fPgDirty:    BOOLEAN;    {TRUE if started printing page}
  48703.                     fImaging:    BOOLEAN;    {used internally}
  48704.                     hPrint:      THPrint;    {print record}
  48705.                     pPrPort:     TPPrPort;   {printing grafPort}
  48706.                     hPic:        PicHandle   {used internally}
  48707.                   END;
  48708.  
  48709. The fPgDirty field is TRUE if anything has already been printed on the current page,
  48710. FALSE if not.
  48711.  
  48712. Your background procedure (if any) can use this record to monitor the state of the
  48713. printing operation.
  48714.  
  48715. æKY TPfPgDir
  48716. TPPfPgDir
  48717. THPfPgDir
  48718. æFc Printing.h
  48719. æT struct
  48720. æD struct TPfPgDir {
  48721.     short iPages;
  48722.     long iPgPos[129]; /*ARRAY [0..iPfMaxPgs] OF LONGINT*/
  48723. };
  48724.  
  48725. typedef struct TPfPgDir TPfPgDir;
  48726. typedef TPfPgDir *TPPfPgDir, **THPfPgDir;
  48727.  
  48728. /* PicFile = a TPfHeader followed by n QuickDraw Pics (whose PicSize is invalid!) */
  48729. æC 
  48730.  
  48731. æKY TPrDlg
  48732. TPPrDlg
  48733. æFc Printing.h
  48734. æT struct
  48735. æD struct TPrDlg {
  48736.     DialogRecord Dlg; /*The Dialog window*/
  48737.     ModalFilterProcPtr pFltrProc; /*The Filter Proc.*/
  48738.     PItemProcPtr pItemProc; /*The Item evaluating proc.*/
  48739.     THPrint hPrintUsr; /*The user's print record.*/
  48740.     Boolean fDoIt;
  48741.     Boolean fDone;
  48742.     long lUser1; /*Four longs for user's to hang global data.*/
  48743.     long lUser2; /*...Plus more stuff needed by the particular printing dialog.*/
  48744.     long lUser3;
  48745.     long lUser4;
  48746. };
  48747.  
  48748. typedef struct TPrDlg TPrDlg;
  48749. typedef TPrDlg *TPPrDlg;
  48750.  
  48751. typedef pascal TPPrDlg (*PDlgInitProcPtr)(THPrint hPrint);
  48752.  
  48753. /* This is the Printing Dialog Record. Only used by folks appending their own dialogs.
  48754. Print Dialog: The Dialog Stream object. */
  48755.  
  48756.  
  48757. æC 
  48758.  
  48759. æKY TGnlData
  48760. æFc Printing.h
  48761. æT struct
  48762. æD struct TGnlData {
  48763.     short iOpCode;
  48764.     short iError;
  48765.     long lReserved; /*more fields here depending on call*/
  48766. };
  48767.  
  48768. typedef struct TGnlData TGnlData;
  48769. æC 
  48770. The Printing Manager has been expanded to include a new procedure called PrGeneral.
  48771. It provides advanced, special-purpose features, intended to solve specific problems
  48772. for those applications that need them.  You can use PrGeneral with version 2.5 and
  48773. later of the ImageWriter driver and version 4.0 and later of the LaserWriter driver. 
  48774. The Pascal declaration of PrGeneral is
  48775.  
  48776. PROCEDURE PrGeneral (pData: Ptr);
  48777.  
  48778. The pData parameter is a pointer to a data block.  The structure of the data block is
  48779. declared as follows:
  48780.  
  48781.   TGnlData = RECORD
  48782.                {1st 8 bytes are common for all PrGeneral calls);
  48783.                iOpCode:    Integer;  {input}
  48784.                iError:     Integer;  {output}
  48785.                lReserved:  LongInt;  {reserved for future use}
  48786.                {more fields here, depending on particular call}
  48787.              END;
  48788.  
  48789. The first field in the TGnlData record is a 2-byte opcode, iOpCode, which acts somewhat
  48790. like a routine selector.   The currently available opcodes are these:
  48791.  
  48792.   •  GetRslData (get resolution data): iOpCode = 4
  48793.   •  SetRsl (set resolution): iOpCode = 5
  48794.   •  DraftBits (bitmaps in draft mode): iOpCode = 6
  48795.   •  NoDraftBits (no bitmaps in draft mode): iOpCode = 7
  48796.   •  GetRotn (get rotation): iOpCode = 8
  48797.  
  48798. GetRslData and SetRsl allow the application to find out what physical resolutions the
  48799. printer supports, and then specify a supported resolution.  DraftBits and noDraftBits
  48800. invoke a new feature of the ImageWriter, allowing bitmaps (imaged via CopyBits) to be
  48801. printed in draft mode.  GetRotn lets an application know whether landscape orientation
  48802. has been selected.  These routines are described in the next sections.
  48803.  
  48804. The second field in the TGnlData record is the error result, iError, returned by the
  48805. print code.   This error only reflects error conditions that occur during the PrGeneral
  48806. call.  For example, if you use an opcode that isn’t implemented in a particular
  48807. printer driver then you will get an OpNotImpl error.  Here are the error codes:
  48808.  
  48809.     CONST
  48810.       NoErr     = 0; {no error}
  48811.       NoSuchRsl = 1; {the resolution you chose isn't available}
  48812.       OpNotImpl = 2; {the driver doesn't support this opcode}
  48813.  
  48814. After calling PrGeneral you should always check PrError.  If NoErr is returned, then
  48815. you can proceed. If ResNotFound is returned, then the current printer driver doesn’t
  48816. support PrGeneral and you should proceed appropriately.
  48817.  
  48818. IError is followed by a four byte reserved field.  The contents of the rest of the
  48819. data block depends on the opcode that the application uses.
  48820.  
  48821. _______________________________________________________________________________
  48822.  
  48823. »GetRslData
  48824.  
  48825. GetRslData (iOpCode = 4) returns a record that lets the application know what resolutions
  48826. are supported by the current printer.  The application can then use SetRsl to tell
  48827. the printer driver which one it will use.  These calls introduce a good deal of
  48828. complexity into your application’s code, and should be used only when necessary.
  48829.  
  48830. æKY TRslRg
  48831. æFc Printing.h
  48832. æT struct
  48833. æD struct TRslRg {
  48834.     short iMin;
  48835.     short iMax;
  48836. };
  48837.  
  48838. typedef struct TRslRg TRslRg;
  48839. æC 
  48840. »GetRslData
  48841.  
  48842. GetRslData (iOpCode = 4) returns a record that lets the application know what resolutions
  48843. are supported by the current printer.  The application can then use SetRsl to tell
  48844. the printer driver which one it will use.  These calls introduce a good deal of
  48845. complexity into your application’s code, and should be used only when necessary.
  48846.  
  48847. This is the format of the input data block for the GetRslData call:
  48848.  
  48849.   TRslRg = RECORD             {used in TGetRslBlk}
  48850.              iMin:  Integer;  {0 if printer supports only discrete resolutions}
  48851.              iMax:  Integer;  {0 if printer supports only discrete resolutions}
  48852.            END;
  48853.  
  48854.   TRslRec = RECORD              {used in TGetRslBlk}
  48855.               iXRsl:  Integer;  {a discrete, physical X resolution}
  48856.               iYRsl:  Integer;  {a discrete, physical Y resolution}
  48857.             END;
  48858.  
  48859.   TGetRslBlk = RECORD    {data block for GetRslData call}
  48860.                  iOpCode:    Integer;    {input; = getRslDataOp}
  48861.                  iError:     Integer;    {output}
  48862.                  lReserved:  LongInt;    {reserved for future use}
  48863.                  iRgType:    Integer;    {output; version number}
  48864.                  XRslRg:     TRslRg;     {output; range of X resolutions}
  48865.                  YRslRg:     TRslRg;     {output; range of Y resolutions}
  48866.                  iRslRecCnt: Integer;    {output; how many RslRecs follow}
  48867.                  rgRslRec:   ARRAY[1..27] OF TRslRec; {output; number filled }
  48868.                                          { depends on printer type}
  48869.                END;
  48870.  
  48871. The iRgType field is much like a version number; it determines the interpretation of
  48872. the data that follows.  An iRgType value of 1 applies both to the LaserWriter and to
  48873. the ImageWriter.
  48874.  
  48875. For variable-resolution printers like the LaserWriter, the resolution range fields
  48876. XRslRg and YRslRg express the ranges of values to which the X and Y resolutions can
  48877. be set.  For discrete-resolution printers like the ImageWriter, the values in the
  48878. resolution range fields are zero.
  48879.  
  48880. Note:  In general, X and Y in these records are the horizontal and vertical
  48881.        directions of the printer, not the document.  In “landscape”
  48882.        orientation, X is horizontal on the printer but vertical on the document.
  48883.  
  48884. After the resolution range information there is a word which gives the number of
  48885. resolution records that contain information.  These records indicate the physical
  48886. resolutions at which the printer can actually print dots.  Each resolution record
  48887. gives an X value and a Y value.
  48888.  
  48889. When you call PrGeneral, use the following data block:
  48890.  
  48891. •••Refer to Figure 5.•••
  48892.  
  48893. Figure 5–Data Block for PrGeneral
  48894.  
  48895. Here is the data block returned by the LaserWriter:
  48896.  
  48897. •••Refer to Figure 6.•••
  48898.  
  48899. Figure 6–Data Block Returned by the LaserWriter
  48900.  
  48901. Notice that all the resolution range numbers are the same for this printer.  There is
  48902. only one resolution record, which gives the physical X and Y resolutions of the
  48903. printer (300 x 300).
  48904.  
  48905. Below is the data block returned by the ImageWriter.
  48906.  
  48907. •••Refer to Figure 7.•••
  48908.  
  48909. Figure 7–Data Block Returned by the ImageWriter
  48910.  
  48911. All the resolution range values are zero, because only discrete resolutions can be
  48912. specified for the ImageWriter.  There are four resolution records giving these discrete
  48913. physical resolutions.
  48914.  
  48915. GetRslData always returns the same information for a particular printer type—it is
  48916. not dependent on what the user does or on printer configuration information.
  48917.  
  48918. æKY TRslRec
  48919. æFc Printing.h
  48920. æT struct
  48921. æD struct TRslRec {
  48922.     short iXRsl;
  48923.     short iYRsl;
  48924. };
  48925.  
  48926. typedef struct TRslRec TRslRec;
  48927. æC 
  48928. »GetRslData
  48929.  
  48930. GetRslData (iOpCode = 4) returns a record that lets the application know what resolutions
  48931. are supported by the current printer.  The application can then use SetRsl to tell
  48932. the printer driver which one it will use.  These calls introduce a good deal of
  48933. complexity into your application’s code, and should be used only when necessary.
  48934.  
  48935. This is the format of the input data block for the GetRslData call:
  48936.  
  48937.   TRslRg = RECORD             {used in TGetRslBlk}
  48938.              iMin:  Integer;  {0 if printer supports only discrete resolutions}
  48939.              iMax:  Integer;  {0 if printer supports only discrete resolutions}
  48940.            END;
  48941.  
  48942.   TRslRec = RECORD              {used in TGetRslBlk}
  48943.               iXRsl:  Integer;  {a discrete, physical X resolution}
  48944.               iYRsl:  Integer;  {a discrete, physical Y resolution}
  48945.             END;
  48946.  
  48947.   TGetRslBlk = RECORD    {data block for GetRslData call}
  48948.                  iOpCode:    Integer;    {input; = getRslDataOp}
  48949.                  iError:     Integer;    {output}
  48950.                  lReserved:  LongInt;    {reserved for future use}
  48951.                  iRgType:    Integer;    {output; version number}
  48952.                  XRslRg:     TRslRg;     {output; range of X resolutions}
  48953.                  YRslRg:     TRslRg;     {output; range of Y resolutions}
  48954.                  iRslRecCnt: Integer;    {output; how many RslRecs follow}
  48955.                  rgRslRec:   ARRAY[1..27] OF TRslRec; {output; number filled }
  48956.                                          { depends on printer type}
  48957.                END;
  48958.  
  48959. The iRgType field is much like a version number; it determines the interpretation of
  48960. the data that follows.  An iRgType value of 1 applies both to the LaserWriter and to
  48961. the ImageWriter.
  48962.  
  48963. For variable-resolution printers like the LaserWriter, the resolution range fields
  48964. XRslRg and YRslRg express the ranges of values to which the X and Y resolutions can
  48965. be set.  For discrete-resolution printers like the ImageWriter, the values in the
  48966. resolution range fields are zero.
  48967.  
  48968. Note:  In general, X and Y in these records are the horizontal and vertical
  48969.        directions of the printer, not the document.  In “landscape”
  48970.        orientation, X is horizontal on the printer but vertical on the document.
  48971.  
  48972. After the resolution range information there is a word which gives the number of
  48973. resolution records that contain information.  These records indicate the physical
  48974. resolutions at which the printer can actually print dots.  Each resolution record
  48975. gives an X value and a Y value.
  48976.  
  48977. When you call PrGeneral, use the following data block:
  48978.  
  48979. •••Refer to Figure 5.•••
  48980.  
  48981. Figure 5–Data Block for PrGeneral
  48982.  
  48983. Here is the data block returned by the LaserWriter:
  48984.  
  48985. •••Refer to Figure 6.•••
  48986.  
  48987. Figure 6–Data Block Returned by the LaserWriter
  48988.  
  48989. Notice that all the resolution range numbers are the same for this printer.  There is
  48990. only one resolution record, which gives the physical X and Y resolutions of the
  48991. printer (300 x 300).
  48992.  
  48993. Below is the data block returned by the ImageWriter.
  48994.  
  48995. •••Refer to Figure 7.•••
  48996.  
  48997. Figure 7–Data Block Returned by the ImageWriter
  48998.  
  48999. All the resolution range values are zero, because only discrete resolutions can be
  49000. specified for the ImageWriter.  There are four resolution records giving these discrete
  49001. physical resolutions.
  49002.  
  49003. GetRslData always returns the same information for a particular printer type—it is
  49004. not dependent on what the user does or on printer configuration information.
  49005.  
  49006. æKY TGetRslBlk
  49007. æFc Printing.h
  49008. æT struct
  49009. æD struct TGetRslBlk {
  49010.     short iOpCode;
  49011.     short iError;
  49012.     long lReserved;
  49013.     short iRgType;
  49014.     TRslRg xRslRg;
  49015.     TRslRg yRslRg;
  49016.     short iRslRecCnt;
  49017.     TRslRec rgRslRec[27];
  49018. };
  49019.  
  49020. typedef struct TGetRslBlk TGetRslBlk;
  49021. æC 
  49022. »GetRslData
  49023.  
  49024. GetRslData (iOpCode = 4) returns a record that lets the application know what resolutions
  49025. are supported by the current printer.  The application can then use SetRsl to tell
  49026. the printer driver which one it will use.  These calls introduce a good deal of
  49027. complexity into your application’s code, and should be used only when necessary.
  49028.  
  49029. This is the format of the input data block for the GetRslData call:
  49030.  
  49031.   TRslRg = RECORD             {used in TGetRslBlk}
  49032.              iMin:  Integer;  {0 if printer supports only discrete resolutions}
  49033.              iMax:  Integer;  {0 if printer supports only discrete resolutions}
  49034.            END;
  49035.  
  49036.   TRslRec = RECORD              {used in TGetRslBlk}
  49037.               iXRsl:  Integer;  {a discrete, physical X resolution}
  49038.               iYRsl:  Integer;  {a discrete, physical Y resolution}
  49039.             END;
  49040.  
  49041.   TGetRslBlk = RECORD    {data block for GetRslData call}
  49042.                  iOpCode:    Integer;    {input; = getRslDataOp}
  49043.                  iError:     Integer;    {output}
  49044.                  lReserved:  LongInt;    {reserved for future use}
  49045.                  iRgType:    Integer;    {output; version number}
  49046.                  XRslRg:     TRslRg;     {output; range of X resolutions}
  49047.                  YRslRg:     TRslRg;     {output; range of Y resolutions}
  49048.                  iRslRecCnt: Integer;    {output; how many RslRecs follow}
  49049.                  rgRslRec:   ARRAY[1..27] OF TRslRec; {output; number filled }
  49050.                                          { depends on printer type}
  49051.                END;
  49052.  
  49053. The iRgType field is much like a version number; it determines the interpretation of
  49054. the data that follows.  An iRgType value of 1 applies both to the LaserWriter and to
  49055. the ImageWriter.
  49056.  
  49057. For variable-resolution printers like the LaserWriter, the resolution range fields
  49058. XRslRg and YRslRg express the ranges of values to which the X and Y resolutions can
  49059. be set.  For discrete-resolution printers like the ImageWriter, the values in the
  49060. resolution range fields are zero.
  49061.  
  49062. Note:  In general, X and Y in these records are the horizontal and vertical
  49063.        directions of the printer, not the document.  In “landscape”
  49064.        orientation, X is horizontal on the printer but vertical on the document.
  49065.  
  49066. After the resolution range information there is a word which gives the number of
  49067. resolution records that contain information.  These records indicate the physical
  49068. resolutions at which the printer can actually print dots.  Each resolution record
  49069. gives an X value and a Y value.
  49070.  
  49071. When you call PrGeneral, use the following data block:
  49072.  
  49073. •••Refer to Figure 5.•••
  49074.  
  49075. Figure 5–Data Block for PrGeneral
  49076.  
  49077. Here is the data block returned by the LaserWriter:
  49078.  
  49079. •••Refer to Figure 6.•••
  49080.  
  49081. Figure 6–Data Block Returned by the LaserWriter
  49082.  
  49083. Notice that all the resolution range numbers are the same for this printer.  There is
  49084. only one resolution record, which gives the physical X and Y resolutions of the
  49085. printer (300 x 300).
  49086.  
  49087. Below is the data block returned by the ImageWriter.
  49088.  
  49089. •••Refer to Figure 7.•••
  49090.  
  49091. Figure 7–Data Block Returned by the ImageWriter
  49092.  
  49093. All the resolution range values are zero, because only discrete resolutions can be
  49094. specified for the ImageWriter.  There are four resolution records giving these discrete
  49095. physical resolutions.
  49096.  
  49097. GetRslData always returns the same information for a particular printer type—it is
  49098. not dependent on what the user does or on printer configuration information.
  49099.  
  49100. æKY TSetRslBlk
  49101. æFc Printing.h
  49102. æT struct
  49103. æD struct TSetRslBlk {
  49104.     short iOpCode;
  49105.     short iError;
  49106.     long lReserved;
  49107.     THPrint hPrint;
  49108.     short iXRsl;
  49109.     short iYRsl;
  49110. };
  49111.  
  49112. typedef struct TSetRslBlk TSetRslBlk;
  49113. æC 
  49114. SetRsl (iOpCode = 5) is used to specify the desired imaging resolution, after using
  49115. GetRslData to determine a workable pair of values.  Below is the format of the data
  49116. block:
  49117.  
  49118.   TSetRslBlk = RECORD                  {data block for SetRsl call}
  49119.                  iOpCode:    Integer;  {input; = setRslOp}
  49120.                  iError:     Integer;  {output}
  49121.                  lReserved:  LongInt;  {reserved for future use}
  49122.                  hPrint:     THPrint;  {input; handle to a valid print record}
  49123.                  iXRsl:      Integer;  {input; desired X resolution}
  49124.                  iYRsl:      Integer;  {input; desired Y resolution}
  49125.                END;
  49126.  
  49127. The hPrint parameter contains the handle of a print record that has previously been
  49128. passed to PrValidate.  If the call executes successfully, the print record is updated
  49129. with the new resolution; the data block comes back with 0 for the error and is otherwise
  49130. unchanged.  If the desired resolution is not supported, the error is set to noSuchRsl
  49131. and the resolution fields are set to the
  49132. printer’s default resolution
  49133.  
  49134. You can undo the effect of a previous call to SetRsl by making another call that
  49135. specifies an unsupported resolution (such as 0 x 0), forcing the default resolution.
  49136.  
  49137. æKY TDftBitsBlk
  49138. æFc Printing.h
  49139. æT struct
  49140. æD struct TDftBitsBlk {
  49141.     short iOpCode;
  49142.     short iError;
  49143.     long lReserved;
  49144.     THPrint hPrint;
  49145. };
  49146.  
  49147. typedef struct TDftBitsBlk TDftBitsBlk;
  49148. æC 
  49149. DraftBits (iOpCode = 6) is implemented on both the ImageWriter and the LaserWriter. 
  49150. On the LaserWriter it does nothing, because the LaserWriter is always in draft mode
  49151. and can always print bitmaps.  Here is the format of the data block:
  49152.  
  49153.   TDftBitsBlk = RECORD                  {data block for DraftBits and }
  49154.                                         { NoDraftBits calls}
  49155.                   iOpCode:    Integer;  {input; = draftBitsOp or noDraftBitsOp}
  49156.                   iError:     Integer;  {output}
  49157.                   lReserved:  LongInt;  {reserved for future use}
  49158.                   hPrint:     THPrint;  {input; handle to a valid print record}
  49159.                 END;
  49160.  
  49161. The hPrint parameter contains the handle of a print record that has previously been
  49162. passed to PrValidate.
  49163.  
  49164. This call forces draft-mode (immediate) printing, and will allow bitmaps to be printed
  49165.  via CopyBits calls.  The virtue of this is that you avoid spooling large masses of
  49166. bitmap data onto the disk, and you also get better performance.
  49167.  
  49168. The following restrictions apply:
  49169.  
  49170.   •  This call should be made before bringing up the print dialog boxes
  49171.      because it affects their appearance.  On the ImageWriter, calling
  49172.      DraftBits disables the landscape icon in the Style dialog, and the
  49173.      Best, Faster, and Draft buttons in the Job dialog box.
  49174.   •  If the printer does not support draft mode, already prints bitmaps
  49175.      in draft mode, or does not print bitmaps at all, this call does nothing.
  49176.   •  Only text and bitmaps can be printed.
  49177.   •  As in the normal draft mode, landscape format is not allowed.
  49178.   •  Everything on the page must be strictly Y-sorted; that is, no reverse
  49179.      paper motion between one string or bitmap and the next.  This means
  49180.      you can’t have two or more objects (text or bitmaps) side by side; the
  49181.      top boundary of each object must be no higher than the bottom of the
  49182.      preceding object.
  49183.  
  49184. The last restriction is important.  If you violate it, you will not like the results.
  49185.  However, if you want two or more bitmaps side by side, you can combine them into one
  49186. before calling CopyBits to print the result.  Similarly, if you are just printing
  49187. bitmaps you can rotate them yourself to achieve landscape printing.
  49188.  
  49189. »NoDraftBits
  49190.  
  49191. NoDraftBits (iOpCode = 7) is implemented on both the ImageWriter and the LaserWriter.
  49192.  On the LaserWriter it does nothing, since the LaserWriter is always in draft mode
  49193. and can always print bitmaps.  The format of the data block is the same as that for
  49194. the DraftBits call.  This call cancels the effect of any preceding DraftBits call. 
  49195. If there was no preceding DraftBits call, or the printer does not support draft-mode
  49196. printing anyway, this call does nothing.
  49197.  
  49198. æKY TGetRotnBlk
  49199. æFc Printing.h
  49200. æT struct
  49201. æD struct TGetRotnBlk {
  49202.     short iOpCode;
  49203.     short iError;
  49204.     long lReserved;
  49205.     THPrint hPrint;
  49206.     Boolean fLandscape;
  49207.     char bXtra;
  49208. };
  49209.  
  49210. typedef struct TGetRotnBlk TGetRotnBlk;
  49211. æC 
  49212. »GetRotn
  49213.  
  49214. GetRotn (iOpCode = 8) is implemented on the ImageWriter and LaserWriter.  Here is the
  49215. format of the data block:
  49216.  
  49217.   TGetRotnBlk = RECORD                     {data block for GetRotn call}
  49218.                   iOpCode:    Integer;     {input; = getRotnOp}
  49219.                   iError:     Integer;     {output}
  49220.                   lReserved:  LongInt;     {reserved for future use}
  49221.                   hPrint:     THPrint;     {input; handle to a valid }
  49222.                                            { print record}
  49223.                   fLandscape: Boolean;     {output; Boolean flag}
  49224.                   bXtra:      SignedByte;  {reserved}
  49225.                 END;
  49226.  
  49227. The hPrint parameter contains a handle to a print record that has previously been
  49228. passed to PrValidate.
  49229.  
  49230. If landscape orientation is selected in the print record, then fLandscape is true.
  49231.  
  49232. æKY PrPurge
  49233. æFc Printing.h
  49234. æT Function
  49235. æD pascal void PrPurge(void); 
  49236. æDT PrPurge()(void);
  49237. æC     PrPurge allows the Printer Driver to be purged from the heap.
  49238.  
  49239. æKY PrNoPurge
  49240. æFc Printing.h
  49241. æT Function
  49242. æD pascal void PrNoPurge(void); 
  49243. æDT PrNoPurge()(void);
  49244. æC     PrNoPurge prevents the Printer Driver from being purged from the
  49245. heap.
  49246.  
  49247. æKY PrOpen
  49248. æFc Printing.h
  49249. æT Function
  49250. æD pascal void PrOpen(void); 
  49251. æDT PrOpen()(void);
  49252. æMM
  49253. æRT 161
  49254. æRI II-157, V-408, N161, VI
  49255. æC 
  49256. [Not in ROM]
  49257.  
  49258. PrOpen prepares the Printing Manager for use. It opens the Printer Driver and the
  49259. printer resource file. If either of these is missing, or if the printer resource file
  49260. isn’t properly formed, PrOpen will do nothing, and PrError will return a Resource
  49261. Manager result code.
  49262.  
  49263. Assembly-language note:  There are no trap macros for these routines. To
  49264.                          print from assembly language, call these Pascal
  49265.                          routines from your program.
  49266.  
  49267. æKY PrClose
  49268. æFc Printing.h
  49269. æT Function
  49270. æD pascal void PrClose(void); 
  49271. æDT PrClose()(void);
  49272. æMM
  49273. æRT 161
  49274. æRI II-157,  V-408, N161, VI
  49275. æC  
  49276. [Not in ROM]
  49277.  
  49278. PrClose releases the memory used by the Printing Manager. It closes the printer
  49279. resource file, allowing the file’s resource map to be removed from memory. It doesn’t
  49280. close the Printer Driver.
  49281.  
  49282. Assembly-language note:  There are no trap macros for these routines. To
  49283.                          print from assembly language, call these Pascal
  49284.                          routines from your program.
  49285.  
  49286. æKY PrintDefault
  49287. æFc Printing.h
  49288. æT Function
  49289. æD pascal void PrintDefault(THPrint hPrint); 
  49290. æDT PrintDefault((THPrint) hPrint);
  49291. æMM
  49292. æRT 122
  49293. æRI II-158, V-408
  49294. æC 
  49295. [Not in ROM]
  49296.  
  49297. PrintDefault fills the fields of the specified print record with default values that
  49298. are stored in the printer resource file. HPrint is a handle to the record, which may
  49299. be a new print record that you’ve just allocated with NewHandle or an existing one
  49300. (from a document, for example).
  49301.  
  49302. æKY PrValidate
  49303. æFc Printing.h
  49304. æT Function
  49305. æD pascal Boolean PrValidate(THPrint hPrint); 
  49306. æDT Boolean myVariable = PrValidate((THPrint) hPrint);
  49307. æMM
  49308. æRT 72, 122, 128, 149
  49309. æRI II-158, V-408, N72-1, 4
  49310. æC 
  49311.  [Not in ROM]
  49312.  
  49313. PrValidate checks the contents of the specified print record for compatibility with
  49314. the current version of the Printing Manager and with the currently installed printer.
  49315. If the record is valid, the function returns FALSE (no change); if invalid, the
  49316. record is adjusted to the default values stored in the printer resource file, and the
  49317. function returns TRUE.
  49318.  
  49319. PrValidate also makes sure all the information in the print record is internally
  49320. self-consistent and updates the print record as necessary. These changes do not
  49321. affect the function’s Boolean result.
  49322.  
  49323. Warning:  You should never call PrValidate (or PrStlDialog or PrJobDialog,
  49324.           which call it) between pages of a document.
  49325.  
  49326. æKY PrStlDialog
  49327. æFc Printing.h
  49328. æT Function
  49329. æD pascal Boolean PrStlDialog(THPrint hPrint); 
  49330. æDT Boolean myVariable = PrStlDialog((THPrint) hPrint);
  49331. æMM
  49332. æRT 72, 95 
  49333. æRI II-158, V-408
  49334. æC 
  49335. [Not in ROM]
  49336.  
  49337. PrStlDialog conducts a style dialog with the user to determine the page dimensions
  49338. and other information needed for page setup. The initial settings displayed in the
  49339. dialog box are taken from the most recent print record. If the user confirms the
  49340. dialog, the results of the dialog are saved in the specified print record, PrValidate
  49341. is called, and the function returns TRUE. Otherwise, the print record is left unchanged
  49342. and the function returns FALSE.
  49343.  
  49344. Note:  If the print record was taken from a document, you should update its
  49345.        contents in the document’s resource file if PrStlDialog returns TRUE.
  49346.        This makes the results of the style dialog “stick” to the document.
  49347.  
  49348. æKY PrJobDialog
  49349. æFc Printing.h
  49350. æT Function
  49351. æD pascal Boolean PrJobDialog(THPrint hPrint); 
  49352. æDT Boolean myVariable = PrJobDialog((THPrint) hPrint);
  49353. æMM
  49354. æRT 72, 95
  49355. æRI II-158, V-408
  49356. æC  
  49357. [Not in ROM]
  49358.  
  49359. PrJobDialog conducts a job dialog with the user to determine the print quality, range
  49360. of pages to print, and so on. The initial settings displayed in the dialog box are
  49361. taken from the printer resource file, where they were remembered from the previous
  49362. job (with the exception of the page range, set to all, and the copies, set to 1).
  49363.  
  49364. If the user confirms the dialog, both the print record and the printer resource file
  49365. are updated, PrValidate is called, and the function returns TRUE. Otherwise, the
  49366. print record and printer resource file are left unchanged and the function returns
  49367. FALSE.
  49368.  
  49369. Note:  Since the job dialog is associated with the Print command, you should
  49370.        proceed with the requested printing operation if PrJobDialog returns
  49371.        TRUE.
  49372.  
  49373. æKY PrStlInit
  49374. æFc Printing.h
  49375. æT Function
  49376. æD pascal TPPrDlg PrStlInit(THPrint hPrint); 
  49377. æDT TPPrDlg myVariable = PrStlInit((THPrint) hPrint);
  49378. æRT 95
  49379. æRI N95-2
  49380. æC 
  49381.  
  49382. æKY PrJobInit
  49383. æFc Printing.h
  49384. æT Function
  49385. æD pascal TPPrDlg PrJobInit(THPrint hPrint); 
  49386. æDT TPPrDlg myVariable = PrJobInit((THPrint) hPrint);
  49387. æRT 95
  49388. æRI N95-2
  49389. æC 
  49390.  
  49391. æKY PrJobMerge
  49392. æFc Printing.h
  49393. æT Function
  49394. æD pascal void PrJobMerge(THPrint hPrintSrc,THPrint hPrintDst); 
  49395. æDT PrJobMerge((THPrint) hPrintSrc,(THPrint) hPrintDst);
  49396. æMM
  49397. æRI II-159, V-408
  49398. æC 
  49399. [Not in ROM]
  49400.  
  49401. PrJobMerge first calls PrValidate for each of the given print records. It then copies
  49402. all of the information set as a result of a job dialog from hPrintSrc to hPrintDst.
  49403. Finally, it makes sure that all the fields of hPrintDst are internally self-consistent.
  49404.  
  49405. PrJobMerge allows you to conduct a job dialog just once and then copy the job information
  49406. to several print records, which means that you can print several documents with one
  49407. dialog. This is useful when printing from the Finder.
  49408.  
  49409. æKY PrDlgMain
  49410. æFc Printing.h
  49411. æT Function
  49412. æD pascal Boolean PrDlgMain(THPrint hPrint,PDlgInitProcPtr pDlgInit); 
  49413. æDT Boolean myVariable = PrDlgMain((THPrint) hPrint,(PDlgInitProcPtr) pDlgInit);
  49414. æRT 95
  49415. æRI N95-2
  49416. æC 
  49417.  
  49418. æKY PrOpenDoc
  49419. æFc Printing.h
  49420. æT Function
  49421. æD pascal TPPrPort PrOpenDoc(THPrint hPrint,TPPrPort pPrPort,Ptr pIOBuf); 
  49422. æDT TPPrPort myVariable = PrOpenDoc((THPrint) hPrint,(TPPrPort) pPrPort,(Ptr) pIOBuf);
  49423. æMM
  49424. æRT 118
  49425. æRI II-159, V-408
  49426. æC 
  49427. [Not in ROM]
  49428.  
  49429. PrOpenDoc initializes a printing grafPort for use in printing a document, makes it
  49430. the current port, and returns a pointer to it.
  49431.  
  49432. HPrint is a handle to the print record for this printing operation; you should already
  49433. have validated this print record.
  49434.  
  49435. Depending on the setting of the bJDocLoop field in the job subrecord, the printing
  49436. grafPort will be set up for draft or spool printing. For spool printing, the spool
  49437. file’s name, volume reference number, and version number are taken from the job
  49438. subrecord.
  49439.  
  49440. PPrPort and pIOBuf are normally NIL. PPrPort is a pointer to the printing grafPort;
  49441. if it’s NIL, PrOpenDoc allocates a new printing grafPort in the heap. Similarly,
  49442. pIOBuf points to an area of memory to be used as an input/output buffer; if it’s NIL,
  49443. PrOpenDoc uses the volume buffer for the spool file’s volume. If you allocate your
  49444. own buffer, it must be 522 bytes long.
  49445.  
  49446. Note:  These parameters are provided because the printing grafPort and
  49447.        input/output buffer are both nonrelocatable objects; to avoid
  49448.        fragmenting the heap, you may want to allocate them yourself.
  49449.  
  49450. You must balance every call to PrOpenDoc with a call to PrCloseDoc.
  49451.  
  49452. æKY PrCloseDoc
  49453. æFc Printing.h
  49454. æT Function
  49455. æD pascal void PrCloseDoc(TPPrPort pPrPort); 
  49456. æDT PrCloseDoc((TPPrPort) pPrPort);
  49457. æMM
  49458. æRT 118
  49459. æRI II-160, V-408
  49460. æC 
  49461. [Not in ROM]
  49462.  
  49463. PrCloseDoc closes the printing grafPort. For draft printing, PrCloseDoc ends the
  49464. printing job. For spool printing, PrCloseDoc ends the spooling process:  The spooled
  49465. document must now be printed. Before printing it, call PrError to find out whether
  49466. spooling succeeded; if it did, you should swap out as much code as possible and then
  49467. call PrPicFile.
  49468.  
  49469. æKY PrOpenPage
  49470. æFc Printing.h
  49471. æT Function
  49472. æD pascal void PrOpenPage(TPPrPort pPrPort,TPRect pPageFrame); 
  49473. æDT PrOpenPage((TPPrPort) pPrPort,(TPRect) pPageFrame);
  49474. æMM
  49475. æRT 72
  49476. æRI II-159, V-408, N72-2
  49477. æC 
  49478. [Not in ROM]
  49479.  
  49480. PrOpenPage begins a new page. The page is printed only if it falls within the page
  49481. range given in the job subrecord.
  49482.  
  49483. For spool printing, the pPageFrame parameter is used for scaling. It points to a
  49484. rectangle to be used as the QuickDraw picture frame for this page:
  49485.  
  49486. TYPE TPRect = ^Rect;
  49487.  
  49488. When you print the spooled document, this rectangle will be scaled (with the QuickDraw
  49489. procedure DrawPicture) to coincide with the rPage rectangle in the printer information
  49490. subrecord. Unless you want the printout to be scaled, you should set pPageFrame to
  49491. NIL—this uses the rPage rectangle as the picture frame, so that the page will be
  49492. printed with no scaling.
  49493.  
  49494. Warning:  Don’t call the QuickDraw function OpenPicture while a page is open
  49495.           (after a call to PrOpenPage and before the following PrClosePage).
  49496.           You can, however, call DrawPicture at any time.
  49497.  
  49498. Warning:  The printing grafPort is completely reinitialized by PrOpenPage.
  49499.           Therefore, you must set grafPort features such as the font and
  49500.           font size for every page that you draw.
  49501.  
  49502. You must balance every call to PrOpenPage with a call to PrClosePage.
  49503.  
  49504. æKY PrClosePage
  49505. æFc Printing.h
  49506. æT Function
  49507. æD pascal void PrClosePage(TPPrPort pPrPort); 
  49508. æDT PrClosePage((TPPrPort) pPrPort);
  49509. æMM
  49510. æRT 72
  49511. æRI II-160, V-408, N72-2
  49512. æC 
  49513. [Not in ROM]
  49514.  
  49515. PrClosePage finishes the printing of the current page. It lets the Printing Manager
  49516. know that you’re finished with this page, so that it can do whatever is required for
  49517. the current printer and printing method.
  49518.  
  49519. æKY PrPicFile
  49520. æFc Printing.h
  49521. æT Function
  49522. æD pascal void PrPicFile(THPrint hPrint,TPPrPort pPrPort,Ptr pIOBuf,Ptr pDevBuf,
  49523.     TPrStatus *prStatus); 
  49524. æDT PrPicFile((THPrint) hPrint,(TPPrPort) pPrPort,(Ptr) pIOBuf,(Ptr) pDevBuf,(
  49525.     TPrStatus) * prStatus);
  49526. æMM
  49527. æRI II-160, V-408
  49528. æC 
  49529. [Not in ROM]
  49530.  
  49531. PrPicFile prints a spooled document. If spool printing is being used, your application
  49532. should normally call PrPicFile after PrCloseDoc.
  49533.  
  49534. HPrint is a handle to the print record for this printing job. The spool file’s name,
  49535. volume reference number, and version number are taken from the job subrecord of this
  49536. print record. After printing is successfully completed, the Printing Manager deletes
  49537. the spool file from the disk.
  49538.  
  49539. You’ll normally pass NIL for pPrPort, pIOBuf, and pDevBuf. PPrPort is a pointer to
  49540. the printing grafPort for this operation; if it’s NIL, PrPicFile allocates a new
  49541. printing grafPort in the heap. Similarly, pIOBuf points to an area of memory to be
  49542. used as an input /output buffer for reading the spool file; if
  49543. it’s NIL, PrPicFile uses the volume buffer for the spool file’s volume. PDevBuf
  49544. points to a device-dependent buffer; if NIL, PrPicFile allocates a buffer in the
  49545. heap.
  49546.  
  49547. Note:  If you provide your own storage for pDevBuf, it has to be big enough
  49548.        to hold the number of bytes indicated by the iDevBytes field of the
  49549.        PrXInfo subrecord.
  49550.  
  49551. Warning:  Be sure not to pass, in pPrPort, a pointer to the same printing
  49552.           grafPort you received from PrOpenDoc. If that port was allocated
  49553.           by PrOpenDoc itself (that is, if the pPrPort parameter to PrOpenDoc
  49554.           was NIL), then PrCloseDoc will have disposed of the port, making
  49555.           your pointer to it invalid. Of course, if you earlier provided your
  49556.           own storage to PrOpenDoc, there’s no reason you can’t use the same
  49557.           storage again for PrPicFile.
  49558.  
  49559. The prStatus parameter is a printer status record that PrPicFile will use to report
  49560. on its progress:
  49561.  
  49562. TYPE  TPrStatus = RECORD
  49563.                     iTotPages:   INTEGER;    {number of pages in spool file}
  49564.                     iCurPage:    INTEGER;    {page being printed}
  49565.                     iTotCopies:  INTEGER;    {number of copies requested}
  49566.                     iCurCopy:    INTEGER;    {copy being printed}
  49567.                     iTotBands:   INTEGER;    {used internally}
  49568.                     iCurBand:    INTEGER;    {used internally}
  49569.                     fPgDirty:    BOOLEAN;    {TRUE if started printing page}
  49570.                     fImaging:    BOOLEAN;    {used internally}
  49571.                     hPrint:      THPrint;    {print record}
  49572.                     pPrPort:     TPPrPort;   {printing grafPort}
  49573.                     hPic:        PicHandle   {used internally}
  49574.                   END;
  49575.  
  49576. The fPgDirty field is TRUE if anything has already been printed on the current page,
  49577. FALSE if not.
  49578.  
  49579. Your background procedure (if any) can use this record to monitor the state of the
  49580. printing operation.
  49581.  
  49582. æKY PrError
  49583. æFc Printing.h
  49584. æT Function
  49585. æD pascal short PrError(void); 
  49586. æDT short myVariable = PrError()(void);
  49587. æMM
  49588. æRT 72, 118
  49589. æRI II-161, V-408, N72-5, N97, N118
  49590. æC 
  49591. [Not in ROM]
  49592.  
  49593. PrError returns the result code left by the last Printing Manager routine. Some
  49594. possible result codes are:
  49595.  
  49596. CONST  noErr       =  0;     {no error}
  49597.        iPrSavPFil  = —1;     {saving print file}
  49598.        controlErr  = —17;    {unimplemented control instruction}
  49599.        iIOAbort    = —27;    {I/O error}
  49600.        iMemFullErr = —108;   {not enough room in heap zone}
  49601.        iPrAbort    =  128;   {application or user requested abort}
  49602.  
  49603.        { The following result codes are LaserWriter-specific }
  49604.  
  49605.                      –4101;  { Printer not found or closed }
  49606.                      –4100;  { Connection just closed }
  49607.                      –4099;  { Write request too big }
  49608.                      –4098;  { Request already active }
  49609.                      –4097;  { Bad connection refnum }
  49610.                      –4096;  { No free CCBs (Connect Control Blocks) available }
  49611.                      –8133;  { PostScript error occurred during transmission }
  49612.                              { of data to printer. Most often caused by a bug }
  49613.                              { in the PostScript code being downloaded. }
  49614.                      –8132;  { Timeout occured. This error is returned when }
  49615.                              { no data has been sent to the printer for 2 }
  49616.                              { minutes. Usually caused by extremely long }
  49617.                              { imaging times. }
  49618.  
  49619. ControlErr is returned by the Device Manager. Other Operating System or Toolbox
  49620. result codes may also be returned; a list of all result codes is given in Appendix
  49621. A.
  49622.  
  49623. Assembly-language note:  The current result code is contained in the global
  49624.                          variable PrintErr.
  49625.  
  49626. æKY PrSetError
  49627. æFc Printing.h
  49628. æT Function
  49629. æD pascal void PrSetError(short iErr); 
  49630. æDT PrSetError((short) iErr);
  49631. æMM
  49632. æRI II-161, V-408
  49633. æC 
  49634. [Not in ROM]
  49635.  
  49636. PrSetError stores the specified value into the global variable where the Printing
  49637. Manager keeps its result code. This procedure is used for canceling a printing operation
  49638. in progress. To do this, call:
  49639.  
  49640. IF PrError <> noErr THEN PrSetError(iPrAbort)
  49641.  
  49642. Assembly-language note:  You can achieve the same effect as PrSetError by
  49643.                          storing directly into the global variable PrintErr.
  49644.                          You shouldn’t, however, store into this variable
  49645.                          if it already contains a nonzero value.
  49646.  
  49647. æKY PrGeneral
  49648. æFc Printing.h
  49649. æT Function
  49650. æD pascal void PrGeneral(Ptr pData); 
  49651. æDT PrGeneral((Ptr) pData);
  49652. æMM
  49653. æRT 72, 128, 173
  49654. æRI V-410, N128
  49655. æC 
  49656. The Printing Manager has been expanded to include a new procedure called PrGeneral.
  49657. It provides advanced, special-purpose features, intended to solve specific problems
  49658. for those applications that need them.  You can use PrGeneral with version 2.5 and
  49659. later of the ImageWriter driver and version 4.0 and later of the LaserWriter driver. 
  49660. The Pascal declaration of PrGeneral is
  49661.  
  49662. PROCEDURE PrGeneral (pData: Ptr);
  49663.  
  49664. The pData parameter is a pointer to a data block.  The structure of the data block is
  49665. declared as follows:
  49666.  
  49667.   TGnlData = RECORD
  49668.                {1st 8 bytes are common for all PrGeneral calls);
  49669.                iOpCode:    Integer;  {input}
  49670.                iError:     Integer;  {output}
  49671.                lReserved:  LongInt;  {reserved for future use}
  49672.                {more fields here, depending on particular call}
  49673.              END;
  49674.  
  49675. The first field in the TGnlData record is a 2-byte opcode, iOpCode, which acts somewhat
  49676. like a routine selector.   The currently available opcodes are these:
  49677.  
  49678.   •  GetRslData (get resolution data): iOpCode = 4
  49679.   •  SetRsl (set resolution): iOpCode = 5
  49680.   •  DraftBits (bitmaps in draft mode): iOpCode = 6
  49681.   •  NoDraftBits (no bitmaps in draft mode): iOpCode = 7
  49682.   •  GetRotn (get rotation): iOpCode = 8
  49683.  
  49684. GetRslData and SetRsl allow the application to find out what physical resolutions the
  49685. printer supports, and then specify a supported resolution.  DraftBits and noDraftBits
  49686. invoke a new feature of the ImageWriter, allowing bitmaps (imaged via CopyBits) to be
  49687. printed in draft mode.  GetRotn lets an application know whether landscape orientation
  49688. has been selected.  These routines are described in the next sections.
  49689.  
  49690. The second field in the TGnlData record is the error result, iError, returned by the
  49691. print code.   This error only reflects error conditions that occur during the PrGeneral
  49692. call.  For example, if you use an opcode that isn’t implemented in a particular
  49693. printer driver then you will get an OpNotImpl error.  Here are the error codes:
  49694.  
  49695.     CONST
  49696.       NoErr     = 0; {no error}
  49697.       NoSuchRsl = 1; {the resolution you chose isn't available}
  49698.       OpNotImpl = 2; {the driver doesn't support this opcode}
  49699.  
  49700. After calling PrGeneral you should always check PrError.  If NoErr is returned, then
  49701. you can proceed. If ResNotFound is returned, then the current printer driver doesn’t
  49702. support PrGeneral and you should proceed appropriately.
  49703.  
  49704. IError is followed by a four byte reserved field.  The contents of the rest of the
  49705. data block depends on the opcode that the application uses.
  49706.  
  49707. _______________________________________________________________________________
  49708.  
  49709. »GetRslData
  49710.  
  49711. GetRslData (iOpCode = 4) returns a record that lets the application know what resolutions
  49712. are supported by the current printer.  The application can then use SetRsl to tell
  49713. the printer driver which one it will use.  These calls introduce a good deal of
  49714. complexity into your application’s code, and should be used only when necessary.
  49715.  
  49716. This is the format of the input data block for the GetRslData call:
  49717.  
  49718.   TRslRg = RECORD             {used in TGetRslBlk}
  49719.              iMin:  Integer;  {0 if printer supports only discrete resolutions}
  49720.              iMax:  Integer;  {0 if printer supports only discrete resolutions}
  49721.            END;
  49722.  
  49723.   TRslRec = RECORD              {used in TGetRslBlk}
  49724.               iXRsl:  Integer;  {a discrete, physical X resolution}
  49725.               iYRsl:  Integer;  {a discrete, physical Y resolution}
  49726.             END;
  49727.  
  49728.   TGetRslBlk = RECORD    {data block for GetRslData call}
  49729.                  iOpCode:    Integer;    {input; = getRslDataOp}
  49730.                  iError:     Integer;    {output}
  49731.                  lReserved:  LongInt;    {reserved for future use}
  49732.                  iRgType:    Integer;    {output; version number}
  49733.                  XRslRg:     TRslRg;     {output; range of X resolutions}
  49734.                  YRslRg:     TRslRg;     {output; range of Y resolutions}
  49735.                  iRslRecCnt: Integer;    {output; how many RslRecs follow}
  49736.                  rgRslRec:   ARRAY[1..27] OF TRslRec; {output; number filled }
  49737.                                          { depends on printer type}
  49738.                END;
  49739.  
  49740. The iRgType field is much like a version number; it determines the interpretation of
  49741. the data that follows.  An iRgType value of 1 applies both to the LaserWriter and to
  49742. the ImageWriter.
  49743.  
  49744. For variable-resolution printers like the LaserWriter, the resolution range fields
  49745. XRslRg and YRslRg express the ranges of values to which the X and Y resolutions can
  49746. be set.  For discrete-resolution printers like the ImageWriter, the values in the
  49747. resolution range fields are zero.
  49748.  
  49749. Note:  In general, X and Y in these records are the horizontal and vertical
  49750.        directions of the printer, not the document.  In “landscape”
  49751.        orientation, X is horizontal on the printer but vertical on the document.
  49752.  
  49753. After the resolution range information there is a word which gives the number of
  49754. resolution records that contain information.  These records indicate the physical
  49755. resolutions at which the printer can actually print dots.  Each resolution record
  49756. gives an X value and a Y value.
  49757.  
  49758. When you call PrGeneral, use the following data block:
  49759.  
  49760. •••Refer to Figure 5.•••
  49761.  
  49762. Figure 5–Data Block for PrGeneral
  49763.  
  49764. Here is the data block returned by the LaserWriter:
  49765.  
  49766. •••Refer to Figure 6.•••
  49767.  
  49768. Figure 6–Data Block Returned by the LaserWriter
  49769.  
  49770. Notice that all the resolution range numbers are the same for this printer.  There is
  49771. only one resolution record, which gives the physical X and Y resolutions of the
  49772. printer (300 x 300).
  49773.  
  49774. Below is the data block returned by the ImageWriter.
  49775.  
  49776. •••Refer to Figure 7.•••
  49777.  
  49778. Figure 7–Data Block Returned by the ImageWriter
  49779.  
  49780. All the resolution range values are zero, because only discrete resolutions can be
  49781. specified for the ImageWriter.  There are four resolution records giving these discrete
  49782. physical resolutions.
  49783.  
  49784. GetRslData always returns the same information for a particular printer type—it is
  49785. not dependent on what the user does or on printer configuration information.
  49786.  
  49787. _______________________________________________________________________________
  49788.  
  49789. »SetRsl
  49790.  
  49791. SetRsl (iOpCode = 5) is used to specify the desired imaging resolution, after using
  49792. GetRslData to determine a workable pair of values.  Below is the format of the data
  49793. block:
  49794.  
  49795.   TSetRslBlk = RECORD                  {data block for SetRsl call}
  49796.                  iOpCode:    Integer;  {input; = setRslOp}
  49797.                  iError:     Integer;  {output}
  49798.                  lReserved:  LongInt;  {reserved for future use}
  49799.                  hPrint:     THPrint;  {input; handle to a valid print record}
  49800.                  iXRsl:      Integer;  {input; desired X resolution}
  49801.                  iYRsl:      Integer;  {input; desired Y resolution}
  49802.                END;
  49803.  
  49804. The hPrint parameter contains the handle of a print record that has previously been
  49805. passed to PrValidate.  If the call executes successfully, the print record is updated
  49806. with the new resolution; the data block comes back with 0 for the error and is otherwise
  49807. unchanged.  If the desired resolution is not supported, the error is set to noSuchRsl
  49808. and the resolution fields are set to the
  49809. printer’s default resolution
  49810.  
  49811. You can undo the effect of a previous call to SetRsl by making another call that
  49812. specifies an unsupported resolution (such as 0 x 0), forcing the default resolution.
  49813.  
  49814. _______________________________________________________________________________
  49815.  
  49816. »DraftBits
  49817.  
  49818. DraftBits (iOpCode = 6) is implemented on both the ImageWriter and the LaserWriter. 
  49819. On the LaserWriter it does nothing, because the LaserWriter is always in draft mode
  49820. and can always print bitmaps.  Here is the format of the data block:
  49821.  
  49822.   TDftBitsBlk = RECORD                  {data block for DraftBits and }
  49823.                                         { NoDraftBits calls}
  49824.                   iOpCode:    Integer;  {input; = draftBitsOp or noDraftBitsOp}
  49825.                   iError:     Integer;  {output}
  49826.                   lReserved:  LongInt;  {reserved for future use}
  49827.                   hPrint:     THPrint;  {input; handle to a valid print record}
  49828.                 END;
  49829.  
  49830. The hPrint parameter contains the handle of a print record that has previously been
  49831. passed to PrValidate.
  49832.  
  49833. This call forces draft-mode (immediate) printing, and will allow bitmaps to be printed
  49834.  via CopyBits calls.  The virtue of this is that you avoid spooling large masses of
  49835. bitmap data onto the disk, and you also get better performance.
  49836.  
  49837. The following restrictions apply:
  49838.  
  49839.   •  This call should be made before bringing up the print dialog boxes
  49840.      because it affects their appearance.  On the ImageWriter, calling
  49841.      DraftBits disables the landscape icon in the Style dialog, and the
  49842.      Best, Faster, and Draft buttons in the Job dialog box.
  49843.   •  If the printer does not support draft mode, already prints bitmaps
  49844.      in draft mode, or does not print bitmaps at all, this call does nothing.
  49845.   •  Only text and bitmaps can be printed.
  49846.   •  As in the normal draft mode, landscape format is not allowed.
  49847.   •  Everything on the page must be strictly Y-sorted; that is, no reverse
  49848.      paper motion between one string or bitmap and the next.  This means
  49849.      you can’t have two or more objects (text or bitmaps) side by side; the
  49850.      top boundary of each object must be no higher than the bottom of the
  49851.      preceding object.
  49852.  
  49853. The last restriction is important.  If you violate it, you will not like the results.
  49854.  However, if you want two or more bitmaps side by side, you can combine them into one
  49855. before calling CopyBits to print the result.  Similarly, if you are just printing
  49856. bitmaps you can rotate them yourself to achieve landscape printing.
  49857. _______________________________________________________________________________
  49858.  
  49859. »NoDraftBits
  49860.  
  49861. NoDraftBits (iOpCode = 7) is implemented on both the ImageWriter and the LaserWriter.
  49862.  On the LaserWriter it does nothing, since the LaserWriter is always in draft mode
  49863. and can always print bitmaps.  The format of the data block is the same as that for
  49864. the DraftBits call.  This call cancels the effect of any preceding DraftBits call. 
  49865. If there was no preceding DraftBits call, or the printer does not support draft-mode
  49866. printing anyway, this call does nothing.
  49867.  
  49868. _______________________________________________________________________________
  49869.  
  49870. »GetRotn
  49871.  
  49872. GetRotn (iOpCode = 8) is implemented on the ImageWriter and LaserWriter.  Here is the
  49873. format of the data block:
  49874.  
  49875.   TGetRotnBlk = RECORD                     {data block for GetRotn call}
  49876.                   iOpCode:    Integer;     {input; = getRotnOp}
  49877.                   iError:     Integer;     {output}
  49878.                   lReserved:  LongInt;     {reserved for future use}
  49879.                   hPrint:     THPrint;     {input; handle to a valid }
  49880.                                            { print record}
  49881.                   fLandscape: Boolean;     {output; Boolean flag}
  49882.                   bXtra:      SignedByte;  {reserved}
  49883.                 END;
  49884.  
  49885. The hPrint parameter contains a handle to a print record that has previously been
  49886. passed to PrValidate.
  49887.  
  49888. If landscape orientation is selected in the print record, then fLandscape is true.
  49889.  
  49890. _______________________________________________________________________________
  49891.  
  49892. »Using PrGeneral
  49893.  
  49894. SetRsl and DraftBits calls may require the print code to suppress certain options in
  49895. the Style and/or Job dialog boxes, therefore they should always be called before any
  49896. call to the Style or Job dialogs.  An application might use PrGeneral as follows:
  49897.  
  49898.   •  Get a new print record by calling PrintDefault, or take an existing
  49899.      one from a document and call PrValidate on it.
  49900.   •  Call GetRslData to find out what the printer is capable of, and decide
  49901.      what resolution to use.  Check PrError to be sure the PrGeneral call
  49902.      is supported on this version of the print code; if the error is
  49903.      ResNotFound, you have older print code and must print accordingly.
  49904.      But if the PrError return is 0, proceed as follows:
  49905.   •  Call SetRsl with the print record and the desired resolution if you wish.
  49906.   •  Call DraftBits to invoke the printing of bitmaps in draft mode if you wish.
  49907.  
  49908. If you call either SetRsl or DraftBits, you should do so before the user sees either
  49909. of the printing dialog boxes.
  49910.  
  49911. æKY PrDrvrOpen
  49912. æFc Printing.h
  49913. æT Function
  49914. æD pascal void PrDrvrOpen(void); 
  49915. æDT PrDrvrOpen()(void);
  49916. æMM
  49917. æRI II-163, V-408
  49918. æC 
  49919. [Not in ROM]
  49920.  
  49921. PrDrvrOpen opens the Printer Driver, reading it into memory if necessary.
  49922.  
  49923. æKY PrDrvrClose
  49924. æFc Printing.h
  49925. æT Function
  49926. æD pascal void PrDrvrClose(void); 
  49927. æDT PrDrvrClose()(void);
  49928. æMM
  49929. æRI II-163, V-408
  49930. æC 
  49931. [Not in ROM]
  49932.  
  49933. PrDrvrClose closes the Printer Driver, releasing the memory it occupies.
  49934. (Notice that PrClose doesn’t close the Printer Driver.)
  49935.  
  49936. æKY PrCtlCall
  49937. æFc Printing.h
  49938. æT Function
  49939. æD pascal void PrCtlCall(short iWhichCtl,long lParam1,long lParam2,long lParam3); 
  49940. æDT PrCtlCall((short) iWhichCtl,(long) lParam1,(long) lParam2,(long) lParam3);
  49941. æMM
  49942. æRT 192
  49943. æRI II-163,  V-408, N17-1
  49944. æC 
  49945. [Not in ROM]
  49946.  
  49947. PrCtlCall calls the Printer Driver’s control routine. The iWhichCtl parameter identifies
  49948. the operation to perform. The following values are predefined:
  49949.  
  49950. CONST  iPrBitsCtl = 4;    {bit map printing}
  49951.        iPrIOCtl   = 5;    {text streaming}
  49952.        iPrDevCtl  = 7;    {printer control}
  49953.  
  49954. These operations are described in detail in the following sections of this chapter.
  49955. The meanings of the lParam1, lParam2, and lParam3 parameters depend on the operation.
  49956.  
  49957. Note:  Advanced programmers:  If you’re making a direct Device Manager
  49958.        Control call, iWhichCtl will be the csCode parameter, and lParam1,
  49959.        lParam2, and lParam3 will be csParam, csParam+4, and csParam+8.
  49960.  
  49961. »Printer Control
  49962.  
  49963. The iPrDevCtl parameter to PrCtlCall is used for several printer control operations.
  49964. The high-order word of the lParam1 parameter specifies the operation to perform:
  49965.  
  49966. CONST
  49967.   iPrBitsCtl    = 4;          {the Bitmap Print Proc's ctl number}
  49968.   lScreenBits   = $00000000;  {the Bitmap Print Proc's Screen Bitmap param}
  49969.   lPaintBits    = $00000001;  {the Bitmap Print Proc's Paint (sq pix) param}
  49970.   lHiScreenBits = $00000002;  {the Bitmap Print Proc's Screen Bitmap param}
  49971.   lHiPaintBits  = $00000003;  {the Bitmap Print Proc's Paint (sq pix) param}
  49972.   iPrIOCtl      = 5;          {the Raw Byte IO Proc's ctl number}
  49973.   iPrEvtCtl     = 6;          {the PrEvent Proc's ctl number; use with Sony }
  49974.                               { printers and one of these CParams:}
  49975.   lPrEvtAll     = $0002FFFD;  {PrEvent Proc's CParam for the whole screen}
  49976.   lPrEvtTop     = $0001FFFD   {PrEvent Proc's CParam for the top window}
  49977.   iPrDevCtl     = 7;          {the PrDevCtl Proc's ctl number}
  49978.   lPrReset      = $00010000;  {OBSOLETE: Use lPrDocOpen instead}
  49979.   lPrDocOpen    = $00010000;  {alias for reset}
  49980.   lPrPageEnd    = $00020000;  {OBSOLETE: Use lPrPageClose instead}
  49981.   lPrPageClose  = $00020000;  {alias for end page}
  49982.   lPrLineFeed   = $00030000;  {the PrDevCtl Proc's CParam for paper advance}
  49983.   lPrLFStd      = $0003FFFF;  {the PrDevCtl Proc's CParam for std paper adv}
  49984.   lPrPageOpen   = $00040000;  {the PrDevCtl Proc's CParam for PageOpen}
  49985.   lPrDocClose   = $00050000;  {the PrDevCtl Proc's CParam for DocClose}
  49986.  
  49987. Other values that may be shown in the interface file are used only by the
  49988. Macintosh system.  The low-order word of lParam1 may specify additional information.
  49989. The lParam2 and lParam3 parameters should always be 0.
  49990.  
  49991. Before starting to print, use
  49992.  
  49993.   PrCtlCall (iPrDevCtl, lPrDocOpen, 0,0);
  49994.   PrCtlCall (iPrDevCtl, lPrPageOpen, 0, 0);
  49995.  
  49996. to reset the printer to its standard initial state. This call should be made only
  49997. once per document. You can also specify the number of copies to make in the low-order
  49998. byte of this parameter; for example, a value of $00010002 specifies two copies.
  49999.  
  50000. The lPrLineFeed and lPrLFStd parameters allow you to achieve the effect of carriage
  50001. returns and line feeds in a printer-independent way:
  50002.  
  50003.   •  LPrLineFeed specifies a carriage return only (with a line feed of 0).
  50004.   •  lPrLFStd causes a carriage return and advances the paper by 1/6 inch
  50005.      (the standard “CR LF” sequence).
  50006.  
  50007. You can also specify the exact number of dots the paper advances in the low-order
  50008. word of the lParam1 parameter. For example, a value of $00030008 for lParam1 causes a
  50009. carriage return and advances the paper eight dots.
  50010.  
  50011. You should use these methods instead of sending carriage returns and line feeds
  50012. directly to the printer.
  50013.  
  50014. The call
  50015.  
  50016.   PrCtlCall (iPrDevCtl, lPrPageClose, 0, 0);
  50017.   PrCtlCall (iPrDevCtl, lPrDocClose, 0, 0);
  50018.  
  50019. does whatever is appropriate for the given printer at the end of each page, such as
  50020. sending a form feed character and advancing past the paper fold. You should use this
  50021. call instead of just sending a form feed yourself.
  50022.  
  50023. _______________________________________________________________________________
  50024.  
  50025. »Bit Map Printing
  50026.  
  50027. To send all or part of a QuickDraw bit map directly to the printer, use
  50028. PrCtlCall(iPrBitsCtl,pBitMap,pPortRect,lControl)
  50029.  
  50030. The pBitMap parameter is a pointer to a QuickDraw bit map; pPortRect is a pointer to
  50031. the rectangle to be printed, in the coordinates of the printing grafPort.
  50032.  
  50033. LControl should be one of the following predefined constants:
  50034.  
  50035. CONST  lScreenBits = 0;    {default for printer}
  50036.        lPaintBits  = 1;    {square dots (72 by 72)}
  50037.  
  50038. The Imagewriter, in standard resolution, normally prints rectangular dots that are
  50039. taller than they are wide (80 dots per inch horizontally by 72 vertically). Since the
  50040. Macintosh 128K and 512K screen has square pixels (approximately 72 per inch both
  50041. horizontally and vertically), lPaintBits gives a truer reproduction of the screen,
  50042. although printing is somewhat slower.
  50043.  
  50044. On the LaserWriter, lControl should always be set to lPaintBits.
  50045.  
  50046. Putting all this together, you can print the entire screen at the default setting
  50047. with
  50048.  
  50049.   PrCtlCall(iPrBitsCtl,ORD(@screenBits),
  50050.                                    ORD(@screenBits.bounds),lScreenBits)
  50051.  
  50052. To print the contents of a single window in square dots, use
  50053.  
  50054.   PrCtlCall(iPrBitsCtl,ORD(@theWindow^.portBits),
  50055.                                    ORD(@theWindow^.portRect),lPaintBits)
  50056.  
  50057. _______________________________________________________________________________
  50058.  
  50059. »Text Streaming
  50060.  
  50061. Text streaming is useful for fast printing of text when speed is more important than
  50062. fancy formatting or visual fidelity. It gives you full access to the printer’s native
  50063. text facilities (such as control or escape sequences for boldface, italic, underlining,
  50064. or condensed or extended type), but makes no use of QuickDraw.
  50065.  
  50066. You can send a stream of characters (including control and escape sequences) directly
  50067. to the printer with
  50068.  
  50069.   PrCtlCall(iPrIOCtl,pBuf,lBufCount,0)
  50070.  
  50071. The pBuf parameter is a pointer to the beginning of the text. The low-order word of
  50072. lBufCount is the number of bytes to transfer; the high-order word must be 0.
  50073.  
  50074. Warning:  Relying on specific printer capabilities and control sequences will
  50075.           make your application printer-dependent. You can use iPrDevCtl to
  50076.           perform form feeds and line feeds in a printer-independent way.
  50077.  
  50078. Note:  Advanced programmers who need more information about sending commands
  50079.        directly to the LaserWriter should see Macintosh Technical Notes and
  50080.        the Apple LaserWriter Reference.
  50081.  
  50082. æKY PrDrvrDCE
  50083. æFc Printing.h
  50084. æT Function
  50085. æD pascal Handle PrDrvrDCE(void); 
  50086. æDT Handle myVariable = PrDrvrDCE()(void);
  50087. æMM
  50088. æRI II-163, V-408
  50089. æC 
  50090. [Not in ROM]
  50091.  
  50092. PrDrvrDCE returns a handle to the Printer Driver’s device control entry.
  50093.  
  50094. æKY PrDrvrVers
  50095. æFc Printing.h
  50096. æT Function
  50097. æD pascal short PrDrvrVers(void); 
  50098. æDT short myVariable = PrDrvrVers()(void);
  50099. æMM
  50100. æRI II-163, V-408
  50101. æC 
  50102. [Not in ROM]
  50103.  
  50104. PrDrvrVers returns the version number of the Printer Driver in the system resource
  50105. file.
  50106.  
  50107. The version number of the Printing Manager is available as the predefined constant
  50108. iPrRelease. You may want to compare the result of PrDrvrVers with iPrRelease to see
  50109. if the Printer Driver in the resource file is the most recent version.
  50110.  
  50111.  
  50112. æKY Processes.h
  50113. æKL GetCurrentProcess
  50114. GetFrontProcess
  50115. GetNextProcess
  50116. GetProcessInformation
  50117. LaunchApplication
  50118. LaunchDeskAccessory
  50119. SameProcess
  50120. SetFrontProcess
  50121. WakeUpProcess
  50122.  
  50123. aeApplicationDied
  50124. aeCreatorType
  50125. aeProcessKeyword
  50126. aeProcessParamType
  50127. aeQuitAll
  50128. aeRestart
  50129. aeShutDown
  50130. appIsDaemon
  50131. appMemFullErr
  50132. appModeErr
  50133. AppParameters
  50134. AppParametersPtr
  50135. extendedBlock
  50136. extendedBlockLen
  50137. hardwareConfigErr
  50138. kCurrentProcess
  50139. kNoProcess
  50140. kSystemProcess
  50141. launchAllow24Bit
  50142. launchContinue
  50143. launchDontSwitch
  50144. LaunchFlags
  50145. launchInhibitDaemon
  50146. launchIsAutomatic
  50147. launchNoFileFlags
  50148. LaunchParamBlockRec
  50149. LaunchPBPtr
  50150. launchUseMinimum
  50151. memFragErr
  50152. mode32BitCompatible
  50153. modeAutomatic
  50154. modeCanBackground
  50155. modeDeskAccessory
  50156. modeDoesActivateOnFGSwitch
  50157. modeGetAppDiedMsg
  50158. modeGetFrontClicks
  50159. modeHighLevelEventAware
  50160. modeLocalAndRemoteHLEvents
  50161. modeMultiLaunch
  50162. modeNeedSuspendResume
  50163. modeOnlyBackground
  50164. modeStationeryAware
  50165. ProcessInfoRec
  50166. ProcessInfoRecPtr
  50167. ProcessSerialNumber
  50168. ProcessSerialNumberPtr
  50169. procNotFound
  50170. protocolErr
  50171.  
  50172. æKY procNotFound
  50173. æFc Processes.h
  50174. æT #define
  50175. æD 
  50176. /* ************************************************************************
  50177.  *                    Error codes not yet in libararies
  50178.  ************************************************************************
  50179.  */
  50180.  
  50181. #define procNotFound (-600) /* no eligible process with specified descriptor */
  50182. æC 
  50183.  
  50184. æKY memFragErr
  50185. æFc Processes.h
  50186. æT #define
  50187. æD #define memFragErr (-601) /* not enough room to launch app w/special requirements */
  50188. æC 
  50189.  
  50190. æKY appModeErr
  50191. æFc Processes.h
  50192. æT #define
  50193. æD #define appModeErr (-602) /* memory mode is 32-bit, but app not 32-bit clean */
  50194. æC 
  50195.  
  50196. æKY protocolErr
  50197. æFc Processes.h
  50198. æT #define
  50199. æD #define protocolErr (-603) /* app made module calls in improper order */
  50200. æC 
  50201.  
  50202. æKY hardwareConfigErr
  50203. æFc Processes.h
  50204. æT #define
  50205. æD #define hardwareConfigErr (-604) /* hardware configuration not correct for call */
  50206. æC 
  50207.  
  50208. æKY appMemFullErr
  50209. æFc Processes.h
  50210. æT #define
  50211. æD #define appMemFullErr (-605) /* application SIZE not big enough for launch */
  50212. æC 
  50213.  
  50214. æKY appIsDaemon
  50215. æFc Processes.h
  50216. æT #define
  50217. æD #define appIsDaemon (-606) /* app is BG-only, and launch flags disallow this */
  50218. æC 
  50219.  
  50220. æKY aeCreatorType
  50221. æFc Processes.h
  50222. æT #define
  50223. æD 
  50224. /* ************************************************************************
  50225.  *                        AppleEvents contributions
  50226.  ************************************************************************
  50227.  
  50228. /* AppleEvents destined for kSystemProcess  */
  50229.  
  50230. #define aeCreatorType 'crea'
  50231. æC 
  50232.  
  50233. æKY aeQuitAll
  50234. æFc Processes.h
  50235. æT #define
  50236. æD #define aeQuitAll 'quia'
  50237. æC 
  50238.  
  50239. æKY aeShutDown
  50240. æFc Processes.h
  50241. æT #define
  50242. æD #define aeShutDown 'shut'
  50243. æC 
  50244.  
  50245. æKY aeRestart
  50246. æFc Processes.h
  50247. æT #define
  50248. æD #define aeRestart 'rest'
  50249. æC 
  50250.  
  50251. æKY aeApplicationDied
  50252. æFc Processes.h
  50253. æT #define
  50254. æD 
  50255. /*  AppleEvents for kSystemProcess  */
  50256.  
  50257. #define aeApplicationDied 'obit'
  50258. æC 
  50259.  
  50260. æKY aeProcessKeyword
  50261. æFc Processes.h
  50262. æT #define
  50263. æD 
  50264. /*  Additional parameter keyword  */
  50265.  
  50266. #define aeProcessKeyword 'proc'
  50267. æC 
  50268.  
  50269. æKY aeProcessParamType
  50270. æFc Processes.h
  50271. æT #define
  50272. æD 
  50273. /*  Additional parameter types  */
  50274.  
  50275. #define aeProcessParamType 'proc'
  50276. æC 
  50277.  
  50278. æKY kNoProcess
  50279. æFc Processes.h
  50280. æT #define
  50281. æD 
  50282. /* ************************************************************************
  50283.  *                            Process identifier.
  50284.  ************************************************************************
  50285.  Various reserved process serial numbers. 
  50286.  */
  50287.  
  50288. #define kNoProcess (0)
  50289. æC 
  50290.  
  50291. æKY kSystemProcess
  50292. æFc Processes.h
  50293. æT #define
  50294. æD #define kSystemProcess (1)
  50295. æC 
  50296.  
  50297. æKY kCurrentProcess
  50298. æFc Processes.h
  50299. æT #define
  50300. æD #define kCurrentProcess (2)
  50301. æC 
  50302.  
  50303. æKY launchContinue
  50304. æFc Processes.h
  50305. æT #define
  50306. æD 
  50307. /*  typedef for unique process identifier 
  50308. ************************************************************************
  50309.  *        Definition of the parameter block passed to _Launch.
  50310.  ************************************************************************
  50311.  Typedef and flags for launchControlFlags field  */
  50312.  
  50313. #define launchContinue 0x4000
  50314. æC 
  50315.  
  50316. æKY launchNoFileFlags
  50317. æFc Processes.h
  50318. æT #define
  50319. æD #define launchNoFileFlags 0x0800
  50320. æC 
  50321.  
  50322. æKY launchUseMinimum
  50323. æFc Processes.h
  50324. æT #define
  50325. æD #define launchUseMinimum 0x0400
  50326. æC 
  50327.  
  50328. æKY launchDontSwitch
  50329. æFc Processes.h
  50330. æT #define
  50331. æD #define launchDontSwitch 0x0200
  50332. æC 
  50333.  
  50334. æKY launchAllow24Bit
  50335. æFc Processes.h
  50336. æT #define
  50337. æD #define launchAllow24Bit 0x0100
  50338. æC 
  50339.  
  50340. æKY launchInhibitDaemon
  50341. æFc Processes.h
  50342. æT #define
  50343. æD #define launchInhibitDaemon 0x0080
  50344. æC 
  50345.  
  50346. æKY launchIsAutomatic
  50347. æFc Processes.h
  50348. æT #define
  50349. æD #define launchIsAutomatic 0x0040
  50350. æC 
  50351.  
  50352. æKY extendedBlock
  50353. æFc Processes.h
  50354. æT #define
  50355. æD 
  50356. /*  Set launchBlockID to extendedBlock to specify that extensions exist.
  50357. * Set launchEPBLength to extendedBlockLen for compatibility.
  50358.  */
  50359.  
  50360. #define extendedBlock ((unsigned short)'LC')
  50361. æC 
  50362.  
  50363. æKY extendedBlockLen
  50364. æFc Processes.h
  50365. æT #define
  50366. æD #define extendedBlockLen (sizeof(LaunchParamBlockRec) - 12)
  50367. æC 
  50368.  
  50369. æKY modeAutomatic
  50370. æFc Processes.h
  50371. æT #define
  50372. æD 
  50373. /* ************************************************************************
  50374.  * Definition of the information block returned by GetProcessInformation.
  50375.  ************************************************************************
  50376.  Bits in the processMode field 
  50377.  */
  50378.  
  50379. #define modeAutomatic 0x00040000
  50380. æC 
  50381.  
  50382. æKY modeDeskAccessory
  50383. æFc Processes.h
  50384. æT #define
  50385. æD #define modeDeskAccessory 0x00020000
  50386. æC 
  50387.  
  50388. æKY modeMultiLaunch
  50389. æFc Processes.h
  50390. æT #define
  50391. æD #define modeMultiLaunch 0x00010000
  50392. æC 
  50393.  
  50394. æKY modeNeedSuspendResume
  50395. æFc Processes.h
  50396. æT #define
  50397. æD #define modeNeedSuspendResume 0x00004000
  50398. æC 
  50399.  
  50400. æKY modeCanBackground
  50401. æFc Processes.h
  50402. æT #define
  50403. æD #define modeCanBackground 0x00001000
  50404. æC 
  50405.  
  50406. æKY modeDoesActivateOnFGSwitch
  50407. æFc Processes.h
  50408. æT #define
  50409. æD #define modeDoesActivateOnFGSwitch 0x00000800
  50410. æC 
  50411.  
  50412. æKY modeOnlyBackground
  50413. æFc Processes.h
  50414. æT #define
  50415. æD #define modeOnlyBackground 0x00000400
  50416. æC 
  50417.  
  50418. æKY modeGetFrontClicks
  50419. æFc Processes.h
  50420. æT #define
  50421. æD #define modeGetFrontClicks 0x00000200
  50422. æC 
  50423.  
  50424. æKY modeGetAppDiedMsg
  50425. æFc Processes.h
  50426. æT #define
  50427. æD #define modeGetAppDiedMsg 0x00000100
  50428. æC 
  50429.  
  50430. æKY mode32BitCompatible
  50431. æFc Processes.h
  50432. æT #define
  50433. æD #define mode32BitCompatible 0x00000080
  50434. æC 
  50435.  
  50436. æKY modeHighLevelEventAware
  50437. æFc Processes.h
  50438. æT #define
  50439. æD #define modeHighLevelEventAware 0x00000040
  50440. æC 
  50441.  
  50442. æKY modeLocalAndRemoteHLEvents
  50443. æFc Processes.h
  50444. æT #define
  50445. æD #define modeLocalAndRemoteHLEvents 0x00000020
  50446. æC 
  50447.  
  50448. æKY modeStationeryAware
  50449. æFc Processes.h
  50450. æT #define
  50451. æD #define modeStationeryAware 0x00000010
  50452. æC 
  50453.  
  50454. æKY LaunchFlags
  50455. æFc Processes.h
  50456. æT typedef
  50457. æD /*************************************************************************
  50458.  *        Definition of the parameter block passed to _Launch.
  50459.  *************************************************************************/
  50460.  
  50461. /* Typedef and flags for launchControlFlags field */
  50462. typedef unsigned short LaunchFlags;
  50463.  
  50464. /* Format for first AppleEvent to pass to new process.  The size of the overall
  50465.  * buffer variable: the message body immediately follows the messageLength.
  50466.  */
  50467. æC 
  50468.  
  50469. æKY ProcessSerialNumber
  50470. ProcessSerialNumberPtr
  50471. æFc Processes.h
  50472. æT struct
  50473. æD struct ProcessSerialNumber {
  50474.     unsigned long HighLongOfPSN;
  50475.     unsigned long LowLongOfPSN;
  50476. };
  50477.  
  50478. typedef struct ProcessSerialNumber ProcessSerialNumber;
  50479. typedef ProcessSerialNumber *ProcessSerialNumberPtr;
  50480.  
  50481. æC 
  50482.  
  50483. æKY AppParameters
  50484. AppParametersPtr
  50485. æFc Processes.h
  50486. æT struct
  50487. æD struct AppParameters {
  50488.     EventRecord theMsgEvent;
  50489.     unsigned long eventRefCon;
  50490.     unsigned long messageLength;
  50491.     signed char messageBuffer[1];
  50492. };
  50493.  
  50494. typedef struct AppParameters AppParameters;
  50495. typedef AppParameters *AppParametersPtr;
  50496.  
  50497. æC 
  50498.  
  50499. æKY LaunchParamBlockRec
  50500. LaunchPBPtr
  50501. æFc Processes.h
  50502. æT struct
  50503. æD struct LaunchParamBlockRec {
  50504.     StringPtr name;
  50505.     unsigned short reserved1;
  50506.     unsigned short launchBlockID;
  50507.     unsigned long launchEPBLength;
  50508.     unsigned short launchFileFlags;
  50509.     LaunchFlags launchControlFlags;
  50510.     unsigned short launchVRefNum;
  50511.     unsigned long launchDirID;
  50512.     ProcessSerialNumber launchProcessSN;
  50513.     unsigned long launchPreferredSize;
  50514.     unsigned long launchMinimumSize;
  50515.     unsigned long launchAvailableSize;
  50516.     AppParametersPtr launchAppParameters;
  50517. };
  50518.  
  50519. typedef struct LaunchParamBlockRec LaunchParamBlockRec;
  50520. typedef LaunchParamBlockRec *LaunchPBPtr;
  50521.  
  50522. æC 
  50523.  
  50524. æKY ProcessInfoRec
  50525. ProcessInfoRecPtr
  50526. æFc Processes.h
  50527. æT struct
  50528. æD struct ProcessInfoRec {
  50529.     unsigned long processInfoLength;
  50530.     StringPtr processName;
  50531.     ProcessSerialNumber processNumber;
  50532.     unsigned long processType;
  50533.     unsigned long int processSignature;
  50534.     unsigned long processMode;
  50535.     Ptr processLocation;
  50536.     unsigned long processSize;
  50537.     unsigned long processFreeMem;
  50538.     ProcessSerialNumber  processLauncher;
  50539.     unsigned long processLaunchDate;
  50540.     unsigned long processActiveTime;
  50541.     StringPtr processFileName;
  50542.     unsigned long processFileDirID;
  50543.     unsigned short processFileVRefNum;
  50544. };
  50545.  
  50546. typedef struct ProcessInfoRec ProcessInfoRec;
  50547. typedef ProcessInfoRec *ProcessInfoRecPtr;
  50548.  
  50549. æC 
  50550.  
  50551. æKY LaunchApplication
  50552. æFc Processes.h
  50553. æT Function
  50554. æTN A9F2
  50555. æD OSErr LaunchApplication(LaunchPBPtr LaunchParams)
  50556.     = {0x202F,0xA9F2}; 
  50557. æDT OSErr myVariable = LaunchApplication((LaunchPBPtr) LaunchParams);
  50558. æC 
  50559. Your application can launch other applications using the LaunchApplication
  50560. function and launch desk accessories using the LaunchDeskAccessory function.
  50561.  
  50562. The LaunchApplication function launches the application from the specified file
  50563. and returns the process serial number, preferred application size, minimum
  50564. application size, available application size, and other information if the
  50565. application is successfully launched.
  50566.  
  50567. Note that if you launch another application without  terminating your
  50568. application, the launched application is not actually launched until the next
  50569. time you call an Event Manager routine such as WaitNextEvent.
  50570.  
  50571. You can set the launchContinue flag in the launchControlFlags field of the
  50572. launch parameter block that lets your application continue after the specified
  50573. application is launched. If you do not set this flag, LaunchApplication
  50574. terminates your application after launching the specified application, even if
  50575. the launch fails. 
  50576.  
  50577. FUNCTION LaunchApplication(LaunchParams: LaunchPBPtr): OSErr;
  50578.  
  50579.  
  50580. Trap macro  _Launch
  50581.  
  50582. On entry    A0: Launch parameter block pointer  
  50583.  
  50584. On exit     A0: Launch parameter block pointer
  50585.             D0: Result code
  50586.  
  50587.  
  50588. Parameter block
  50589.   Æ   0   name                 long     pointer to buffer for app name
  50590.   Æ   6   launchBlockID        word     extended block
  50591.   Æ   8   launchEPBLength      long     length of following fields
  50592.   Æ   12  launchFileFlags      word     Finder flags for the application file
  50593.   Æ   14  launchControlFlags   word     flags for execution options
  50594.   Æ   16  launchVRefNum        word     volume reference number or
  50595.                                          working directory reference number
  50596.   Æ   18  launchDirID          long     directory ID or 0
  50597.   ¨   22  launchProcessSN      2 longs  process serial number
  50598.   ¨   30  launchPreferredSize  long     preferred application partition size
  50599.   ¨   34  launchMinimumSize    long     minimum application partition size
  50600.   ¨   38  launchAvailableSize  long     maximum available partition size
  50601.   Æ   42  launchAppParameters  long     high-level event for launched app
  50602.  
  50603. Field descriptions
  50604.  
  50605. name                 The name of the application file to launch. 
  50606.  
  50607. launchBlockID        Contains the constant extendedBlock to indicate that you  
  50608.  
  50609.                      are using the fields following it in the launch parameter 
  50610.                      block.
  50611.  
  50612. launchEPBLength      The length of the fields following this field in the launch
  50613.  
  50614.                      parameter block. Use the constant extendedBlockLen to 
  50615.                      specify this value.
  50616.  
  50617. launchFileFlags      The Finder flags for the application file. Set the    
  50618.                      launchNoFileFlags constant in the launchControlFlags field,
  50619.  
  50620.                      if you want the LaunchApplication function to extract the 
  50621.                      Finder flags from the application file for you. 
  50622.  
  50623. launchControlFlags   The launch options that determine how the application is 
  50624.                      launched. You can specify these constant values to set 
  50625.                      various options.
  50626.  
  50627.                      CONST
  50628.                      launchContinue       = $4000;  
  50629.                      launchNoFileFlags    = $0800;  
  50630.                      launchUseMinimum     = $0400;
  50631.                      launchDontSwitch     = $0200;
  50632.                      launchAllow24Bit     = $0100;
  50633.                      launchInhibitDaemon  = $0080;
  50634.                      launchIsAutomatic    = $0040;
  50635.                      
  50636.                      See “Specifying Launch Options” earlier in this chapter for
  50637.  
  50638.                      a complete description of these flags.
  50639.  
  50640. launchVRefNum        The volume reference number or working directory for the 
  50641.                      application file.
  50642.  
  50643. launchDirID          The parent directory reference number for the application 
  50644.                      file or 0 if launchVRefNum specifies a directory reference 
  50645.                      number.
  50646.  
  50647. launchProcessSN      The process serial number returned to your application if 
  50648.                      the launch is successful. You can use this process serial 
  50649.                      number in other Process Manager routines to refer to the 
  50650.                      launched application.
  50651.  
  50652. launchPreferredSize  The preferred partition size for the launched application 
  50653.  
  50654.                      as specified in the launched application’s 'SIZE' resource.
  50655.  
  50656.                      This value is not returned to your application if the 
  50657.                      application was already open. 
  50658.  
  50659. launchMinimumSize    The minimum partition size for the launched application as 
  50660.                      specified in the launched application’s 'SIZE' resource. 
  50661.                      This value is not returned to your application if the 
  50662.                      application was already open. 
  50663.  
  50664. launchAvailableSize  The maximum partition size that is available for
  50665. allocation. 
  50666.                      This value is returned to your application only if the 
  50667.                      MemFullErr result code is returned. If the application 
  50668.                      fails to launch (because there isn’t enough memory) you can
  50669.  
  50670.                      use this value to determine if there is enough memory 
  50671.                      available to launch in the minimum size. 
  50672.  
  50673. Result codes
  50674.    noErr             0        No error
  50675.    memFragErr        -601     Not enough room to launch application with 
  50676.                               special requirements 
  50677.    appModeErr        -602     Memory mode is 32-bit, but application is not 
  50678.                               32-bit clean
  50679.    appIsDaemon       -606     Application is background-only, and launch flags 
  50680.  
  50681.                               don’t allow this
  50682.    appMemFullErr     -605     More memory for the partition size is required 
  50683.                               than the amount specified in the 'SIZE' resource 
  50684.    MemFullErr        -108     Not enough memory to allocate the partition size
  50685.                               specified in the 'SIZE' resource 
  50686.  
  50687. æKY LaunchDeskAccessory
  50688. æFc Processes.h
  50689. æT Function
  50690. æTN A88F
  50691. æD 
  50692. pascal OSErr LaunchDeskAccessory(StringPtr pFileName,short fileVRefNum,
  50693.     long fileDirID,StringPtr pDAName)
  50694.     = {0x3F3C,0x0036,0xA88F}; 
  50695. æDT OSErr myVariable = LaunchDeskAccessory((StringPtr) pFileName,(short) fileVRefNum,()
  50696.     long fileDirID,(StringPtr) pDAName);
  50697. æC 
  50698. Your application can launch desk accessories using the LaunchDeskAccessory
  50699. routine. Use this routine only when your application needs to launch a desk
  50700. accessory for some reason other than the user choosing a desk accessory from the
  50701. Apple menu. (When the user chooses a desk accessory from the Apple menu, use the
  50702. OpenDeskAcc function.)
  50703.  
  50704. FUNCTION LaunchDeskAccessory(pFileName: StringPtr; fileVRefNum: Integer; 
  50705.                              fileDirID: LongInt; pDAName: StringPtr): OSErr;
  50706.  
  50707. LaunchDeskAccessory searches the resource fork of the file specified by the
  50708. given file name, directory ID, and volume reference number for the desk
  50709. accessory with the specified (or 'DRVR' resource) name. If the 'DRVR' resource
  50710. name is found, LaunchDeskAccessory launches the desk accessory. 
  50711.  
  50712. Specify the name of the file to search in the pFileName parameter. Specify NIL
  50713. for pFileName if you want to search the current resource chain. Specify the
  50714. volume reference number in the fileVRefNum parameter. Specify the file’s
  50715. directory ID in the fileDirID parameter. 
  50716.  
  50717. Specify the 'DRVR' resource name of the desk accessory to launch in the pDAName
  50718. parameter. Specify NIL in pDAName if you want to launch the first 'DRVR'
  50719. resource found in the file. The LaunchDeskAccessory function opens the specified
  50720. resource file for exclusive access, so you cannot launch more than one desk
  50721. accessory from the same resource file.
  50722.  
  50723. If the desk accessory is already open, it is brought to the front.
  50724.  
  50725. LaunchDeskAccessory launches the desk accessory in the application’s heap if the
  50726. Option key is held down and the file is in the current resource chain.
  50727. Otherwise, the desk accessory is given its own partition and launched in the
  50728. system heap.  
  50729.  
  50730. Result codes
  50731.    noErr             0        No error
  50732.    ResNotFound       -192     Resource not found
  50733.  
  50734.  
  50735.  
  50736. æKY GetCurrentProcess
  50737. æFc Processes.h
  50738. æT Function
  50739. æTN A88F
  50740. æD pascal OSErr GetCurrentProcess(ProcessSerialNumber *psnStorage)
  50741.     = {0x3F3C,0x0037,0xA88F}; 
  50742. æDT OSErr myVariable = GetCurrentProcess((ProcessSerialNumber *) psnStorage);
  50743. æC 
  50744. You can use the process management routines to get the process serial number for
  50745. a particular process, to get information about processes, or to change the
  50746. scheduling status of a process.
  50747.  
  50748. FUNCTION GetCurrentProcess(VAR PSN: ProcessSerialNumber): OSErr;
  50749.  
  50750. The GetCurrentProcess function returns in the PSN parameter the process serial
  50751. number for the process that is currently executing. The currently executing
  50752. process is the process that is currently accessing the CPU; this is the
  50753. application associated with the CurrentA5 global variable and the application
  50754. can be running in either the foreground or the background. 
  50755.  
  50756. Applications can use this function to return their own process serial number.
  50757. Drivers can use this function to find the process serial number of the current
  50758. process. You can use the returned process serial number in other Process Manager
  50759. routines or to specify a target application when sending a high-level event.
  50760.  
  50761. Result codes
  50762.    noErr                   0       No error
  50763.  
  50764.  
  50765. æKY GetFrontProcess
  50766. æFc Processes.h
  50767. æT Function
  50768. æTN A88F
  50769. æD pascal OSErr GetFrontProcess(ProcessSerialNumber *psnStorage)
  50770.     = {0x70FF,0x2F00,0x3F3C,0x0039,0xA88F}; 
  50771. æDT OSErr myVariable = GetFrontProcess((ProcessSerialNumber *) psnStorage);
  50772. æC 
  50773. The GetFrontProcess function returns in the PSN parameter the process serial
  50774. number for the process running in the foreground. You can use the process serial
  50775. number returned in the PSN parameter in other process management routines.
  50776.  
  50777. If there isn’t a process running in the foreground, GetFrontProcess returns the
  50778. result code procNotFound. 
  50779.  
  50780. Result codes
  50781.    noErr                   0       No error
  50782.    paramErr                -50     Process serial number is invalid
  50783.    procNotFound            -600    No process in the foreground
  50784.  
  50785.  
  50786. æKY GetNextProcess
  50787. æFc Processes.h
  50788. æT Function
  50789. æTN A88F
  50790. æD pascal OSErr GetNextProcess(ProcessSerialNumber *pParamPSN)
  50791.     = {0x3F3C,0x0038,0xA88F}; 
  50792. æDT OSErr myVariable = GetNextProcess((ProcessSerialNumber *) pParamPSN);
  50793. æC 
  50794. The Process Manager maintains a list of all open processes. You can derive this
  50795. list by using repetitive calls to GetNextProcess. You can begin generating the
  50796. list by calling GetNextProcess and specifying kNoProcess in the PSN parameter.
  50797. You can then use the returned process serial number to get the process serial
  50798. number for the next process. GetNextProcess returns the result code ProcNotFound
  50799. when the end of the list is reached.
  50800.  
  50801. The process serial number you specify in the PSN parameter should be a valid
  50802. process serial number returned from GetNextProcess, GetFrontProcess, or
  50803. GetCurrentProcess, or the defined constant kNoProcess.
  50804.  
  50805. Result codes
  50806.    noErr                    0       No error
  50807.    paramErr                 -50     Process serial number is invalid
  50808.    procNotFound             -600    No process in the process list following the
  50809.  
  50810.                                     specified process
  50811.  
  50812. æKY GetProcessInformation
  50813. æFc Processes.h
  50814. æT Function
  50815. æTN A88F
  50816. æD pascal OSErr GetProcessInformation(ProcessSerialNumberPtr pPSN,ProcessInfoRecPtr pStorage)
  50817.     = {0x3F3C,0x003A,0xA88F}; 
  50818. æDT OSErr myVariable = GetProcessInformation((ProcessSerialNumberPtr) pPSN,(ProcessInfoRecPtr)
  50819.                        pStorage);
  50820. æC 
  50821. The GetProcessInformation function returns information about the specified
  50822. process in a process information record. The information returned in the info
  50823. parameter includes the application’s name as it appears in the Apple menu, the
  50824. type and signature of the application, address of the application partition, the
  50825. number of bytes in the application partition, the number of free bytes in the
  50826. application heap, the application that launched the application, the time at
  50827. which the application was launched, and the location of the application file.
  50828.  
  50829. The GetProcessInformation function also returns information about the
  50830. application’s 'SIZE' resource and indicates whether the process is an
  50831. application or a desk accessory.
  50832.  
  50833. You need to specify values for the processInfoLength, processName, and
  50834. processFileName fields of the process information record. Specify the length of
  50835. the process information record in the processInfoLength field. If you do not
  50836. want information returned in the processName and processFileName fields specify
  50837. NIL for these fields. Otherwise, you should allocate at least 32 bytes of
  50838. storage for the strings pointed to by these fields.
  50839.  
  50840. The process serial number you specify in the PSN parameter should be a valid
  50841. process serial number returned from GetNextProcess, GetFrontProcess,
  50842. GetCurrentProcess, or a high-level event. You can use the constant
  50843. kCurrentProcess to get information about the current process.
  50844.  
  50845. Result codes
  50846.    noErr                   0       No error
  50847.    paramErr                -50     Process serial number is invalid
  50848.  
  50849. æKY SetFrontProcess
  50850. æFc Processes.h
  50851. æT Function
  50852. æTN A88F
  50853. æD pascal OSErr SetFrontProcess(ProcessSerialNumberPtr pPSN)
  50854.     = {0x3F3C,0x003B,0xA88F}; 
  50855. æDT OSErr myVariable = SetFrontProcess((ProcessSerialNumberPtr) pPSN);
  50856. æC 
  50857. The SetFrontProcess function schedules the specified process to become the
  50858. foreground process. The specified process becomes the foreground process after
  50859. the current foreground process makes a subsequent call to an Event Manager
  50860. routine.
  50861.  
  50862. The process serial number in the PSN parameter should be a valid process serial
  50863. number returned from GetNextProcess, GetFrontProcess, GetCurrentProcess, or a
  50864. high-level event. You can also use the constant kNoProcess to refer to the first
  50865. process in the process list, and you can use the constant kCurrentProcess to
  50866. refer to the current process.
  50867.  
  50868. If the specified process serial number is invalid or if the specified process is
  50869. a background-only application, SetFrontProcess returns a non-zero result code
  50870. and does not change the current foreground process.
  50871.  
  50872. Result codes
  50873.    noErr                   0       No error
  50874.    procNotFound            -600    Process with specified process serial number
  50875.                                    doesn’t exist or process is suspended by 
  50876.                                    high-level debugger
  50877.    appIsDaemon             -606    Specified process is background-only
  50878.  
  50879.  
  50880. æKY WakeUpProcess
  50881. æFc Processes.h
  50882. æT Function
  50883. æTN A88F
  50884. æD pascal OSErr WakeUpProcess(ProcessSerialNumberPtr pPSN)
  50885.     = {0x3F3C,0x003C,0xA88F}; 
  50886. æDT OSErr myVariable = WakeUpProcess((ProcessSerialNumberPtr) pPSN);
  50887. æC 
  50888. The WakeUpProcess function makes a suspended process eligible to receive CPU
  50889. time. For example, when a process specifies a nonzero value for the sleep
  50890. parameter in the WaitNextEvent function, and there are no events for that
  50891. process pending in the event queue, the process is suspended. This process
  50892. remains suspended until the time specified in the sleep parameter expires or an
  50893. event becomes available for that process. You can use WakeUpProcess to make the
  50894. process eligible for execution before the time specified in the sleep parameter
  50895. expires.
  50896.  
  50897. The WakeUpProcess function does not change the order of the processes scheduled
  50898. for execution; it only makes the specified process eligible for execution. 
  50899. The process serial number specified in the PSN parameter should be a valid
  50900. process serial number returned from GetNextProcess, GetFrontProcess,
  50901. GetCurrentProcess, or from a high-level event.
  50902.  
  50903. A driver or completion routine can use the constant kCurrentProcess to refer to
  50904. the current process.
  50905.  
  50906. Result codes
  50907.    noErr                   0       No error
  50908.    procNotFound            -600    Suspended process with specified process
  50909.                                    serial number doesn’t exist
  50910.  
  50911.  
  50912. æKY SameProcess
  50913. æFc Processes.h
  50914. æT Function
  50915. æTN A88F
  50916. æD pascal OSErr SameProcess(ProcessSerialNumberPtr pPSN1,ProcessSerialNumberPtr pPSN2,
  50917.     Boolean *pResult)
  50918.     = {0x3F3C,0x003D,0xA88F}; 
  50919. æDT OSErr myVariable = SameProcess((ProcessSerialNumberPtr) pPSN1,(ProcessSerialNumberPtr) pPSN2,(
  50920.     Boolean) * pResult);
  50921. æC 
  50922. The SameProcess function compares two process serial numbers and determines
  50923. whether they refer to the same process. If the process serial numbers specified
  50924. in the PSN1 and PSN2 parameters refer to the same process, the SameProcess
  50925. function returns TRUE in the result parameter; otherwise, it returns FALSE in
  50926. the result parameter.
  50927.  
  50928. When you compare two process serial numbers use the SameProcess function rather
  50929. than any other means, because the interpretation of the bits in a process serial
  50930. number are internal to the Process Manager.
  50931.  
  50932. The process serial numbers you use should be valid process serial numbers
  50933. returned from GetNextProcess, GetFrontProcess, GetCurrentProcess, or a
  50934. high-level event. You can also use the constant kCurrentProcess to refer to the
  50935. current process.
  50936.  
  50937. Result codes
  50938.    noErr                   0       No error
  50939.    paramErr                -50     Process serial number is invalid
  50940.  
  50941.  
  50942.  
  50943. æKY QDOffscreen.h
  50944. æKL AllowPurgePixels
  50945. CTabChanged
  50946. DisposeGWorld
  50947. DisposeScreenBuffer
  50948. GDeviceChanged
  50949. GetGWorld
  50950. GetGWorldDevice
  50951. GetGWorldPixMap
  50952. GetPixBaseAddr
  50953. GetPixelsState
  50954. LockPixels
  50955. NewGWorld
  50956. NewScreenBuffer
  50957. NewTempScreenBuffer
  50958. NoPurgePixels
  50959. OffscreenVersion
  50960. Pixmap32Bit
  50961. PixPatChanged
  50962. PortChanged
  50963. QDDone
  50964. SetGWorld
  50965. SetPixelsState
  50966. UnlockPixels
  50967. UpdateGWorld
  50968.  
  50969. cDepthErr
  50970. GWorldFlags
  50971. GWorldPtr
  50972.  
  50973. æKY cDepthErr
  50974. æFc QDOffscreen.h
  50975. æT #define
  50976. æD 
  50977. /* New error codes */
  50978.  
  50979. #define cDepthErr -157 /*invalid pixel depth*/
  50980. æC 
  50981.  
  50982. æKY GWorldFlags
  50983. æFc QDOffscreen.h
  50984. æT enum
  50985. æD enum {pixPurge = 1 << pixPurgeBit,noNewDevice = 1 << noNewDeviceBit,useMFTemp = 1 << useMFTempBit,
  50986.     keepLocal = 1 << keepLocalBit,pixelsPurgeable = 1 << pixelsPurgeableBit,
  50987.     pixelsLocked = 1 << pixelsLockedBit,mapPix = 1 << mapPixBit,newDepth = 1 << newDepthBit,
  50988.     alignPix = 1 << alignPixBit,newRowBytes = 1 << newRowBytesBit,reallocPix = 1 << reallocPixBit,
  50989.     clipPix = 1 << clipPixBit,stretchPix = 1 << stretchPixBit,ditherPix = 1 << ditherPixBit,
  50990.     gwFlagErr = 1 << gwFlagErrBit};
  50991. typedef unsigned long GWorldFlags;
  50992. æC 
  50993.  
  50994. æKY GWorldPtr
  50995. æFc QDOffscreen.h
  50996. æT typedef
  50997. æD 
  50998. /* Type definition of a GWorldPtr */
  50999.  
  51000. typedef CGrafPtr GWorldPtr;
  51001. æC 
  51002.  
  51003. æKY NewGWorld
  51004. æFc QDOffscreen.h
  51005. æT Function
  51006. æD 
  51007. pascal QDErr NewGWorld(GWorldPtr *offscreenGWorld,short PixelDepth,Rect *boundsRect,
  51008.     CTabHandle cTable,GDHandle aGDevice,GWorldFlags flags)
  51009.     = {0x203C,0x0016,0x0000,0xAB1D}; 
  51010. æDT QDErr myVariable = NewGWorld((GWorldPtr *) offscreenGWorld,(short) PixelDepth,(Rect *) boundsRect,()
  51011.     CTabHandle cTable,(GDHandle) aGDevice,(GWorldFlags) flags);
  51012. æC 
  51013. The NewGWorld function creates a graphics environment: it allocates an offscreen
  51014. port and pixel map and its associated offscreen memory. It also allocates a new
  51015. offscreen GDevice record unless you specify that an existing GDevice record be
  51016. used—either one you supply or the deepest in the rectangle defined by the
  51017. boundsRect parameter.  NewGWorld sets the pixel depth, boundary rectangle, color
  51018. table, and GWorld flags. It returns a pointer to the offscreen graphics world in
  51019. offscreenGWorld.
  51020.  
  51021. The NewGWorld function lets you create an offscreen environment optimized either
  51022. for your image’s characteristics (for example, its best pixel depth), or for the
  51023. fastest copying on to the available devices. 
  51024.  
  51025. A value of 0 in the pixelDepth parameter requests that the deepest device
  51026. intersecting your boundsRect value in screen space be used for the offscreen
  51027. GDevice record. In this use of the NewGWorld routine you create an offscreen
  51028. graphics world optimized for the attached graphic devices, rather than one
  51029. optimized for the pixel depth of your image. The port’s portRect is set to the
  51030. same size as boundsRect with the topLeft coordinates set to (0, 0). The PixMap’s
  51031. bounds and the device’s gdRect are computed so that CopyBits operations between
  51032. the offscreen PixMap and the screen are optimized. (Typically, the PixMap’s
  51033. bounds will be a few pixels wider than those of the portRect.) 
  51034.  
  51035. Parameter implications of this alternate use of the NewGWorld routine are noted
  51036. in each parameter description.
  51037.  
  51038. pixelDepth   The pixelDepth field determines the pixel resolution of the 
  51039.              offscreen world. Possible depths are 0, 1, 2, 4, 8, 16, and 32 bits
  51040.  
  51041.              per pixel. 
  51042.              If you specify a pixelDepth of 0, the NewGWorld function uses the  
  51043.              deepest device intersecting the rectangle specified by your 
  51044.              boundsRect parameter to create the offscreen GDevice record. 
  51045.  
  51046. boundsRect   The boundsRect field determines the offscreen PixMap’s size and 
  51047.              coordinate system, and becomes the offscreen port’s portRect, the 
  51048.              offscreen PixMap’s bounds, and the offscreen device’s gdRect. It is
  51049.  
  51050.              used to determine the PixMap’s rowBytes and the size necessary to 
  51051.              allocate the offscreen buffer.  
  51052.              If you specify a pixelDepth of 0, the boundsRect parameter is taken
  51053.  
  51054.              in global coordinates to find the deepest device that intersects 
  51055.              its rectangle.
  51056.  
  51057. cTable       The cTable field is a handle to the color table to be used. 
  51058.              NewGWorld makes a copy of that color table and puts its reference 
  51059.              in the offscreen PixMap. It is your application’s responsibility to
  51060.  
  51061.              make sure that cTable is a valid color table for the pixelDepth. If
  51062.  
  51063.              cTable is NIL, the default color table for the pixelDepth is used. 
  51064.   
  51065.              If you specify a pixelDepth of 0, the color table of the deepest 
  51066.              device intersecting the boundsRect rectangle is used, and the  
  51067.              cTable parameter is ignored. 
  51068.  
  51069. flags        The flags field provides some options to the application. It can be
  51070.  
  51071.              a combination of the flags pixPurge, NoNewDevice, and useMFTempBit,
  51072.  
  51073.              all members of the GWorldFlags set. 
  51074.  
  51075.              If you set the pixPurge flag, NewGWorld makes the offscreen buffer 
  51076.              a purgeable block. Before drawing to or from the offscreen graphics
  51077.  
  51078.              world, your application should call the LockPixels function and 
  51079.              ensure that it returns TRUE. If LockPixels returns FALSE, the 
  51080.              offscreen buffer has been purged and your application should either
  51081.  
  51082.              call UpdateGWorld to reallocate it or draw directly in the window 
  51083.              it represents. Never draw to a purged offscreen buffer.
  51084.   
  51085.              If you set noNewDevice, NewGWorld does not create a new offscreen 
  51086.              device and the depth and color table of aGDevice is used to create
  51087.  
  51088.              the offscreen graphics world. (If you specify a pixelDepth of 0, 
  51089.              the deepest device intersecting the boundsRect rectangle is used.)
  51090.   
  51091.              NewGWorld keeps a reference to whichever device it uses in the 
  51092.              offscreen graphics world data structure, and the SetGWorld 
  51093.              procedure uses that to set the current device.  
  51094.   
  51095.              Note that, to use a custom color table in an offscreen graphics 
  51096.              world, you need to create the associated offscreen device, because 
  51097.              Color QuickDraw needs the device’s inverse table to draw.  
  51098.    
  51099.              If you set the useMFTempBitflag, NewGWorld will allocate pixels in 
  51100.              MultiFinder temporary memory. You should only use MultiFinder 
  51101.              temporary memory for fleeting purposes, and only in conjunction 
  51102.              with the AllowPurgePixels procedure so that other applications can 
  51103.              launch.
  51104.  
  51105. aGDevice     NewGWorld uses the GDevice record specified in the aGDevice field 
  51106.              to create the offscreen graphics world when noNewDevice is set. 
  51107.   
  51108.              If pixelDepth is 0 (or if noNewDevice is not set) the aGDevice 
  51109.              field is ignored and should be set to NIL. 
  51110.  
  51111. The offscreen port is initialized by calling OpenCPort. The port’s visRgn is set
  51112. to a rectangular region coincident with its portRect. The offscreen device is
  51113. initialized according to pixelDepth, boundsRect, cTable, and default values. An
  51114. inverse table is generated with MakeITable, unless one of the screen devices has
  51115. the same color table as the offscreen device, in which case the inverse table is
  51116. copied from that device.
  51117.  
  51118. You can compute the size of the offscreen buffer using the formula: 
  51119.  
  51120.   rowBytes * (boundsRect.bottom - boundsRect.top)  
  51121.  
  51122. The actual address of the offscreen buffer is not accessible directly from the
  51123. PixMap. If you need to access the pixels without going through QuickDraw, call
  51124. GetPixBaseAddr to get a pointer to the pixels.
  51125.      
  51126. Result codes  
  51127. noErr        No error
  51128. cDepthErr    Invalid pixel resolution
  51129. paramErr     Illegal parameter 
  51130.  
  51131. æKY LockPixels
  51132. æFc QDOffscreen.h
  51133. æT Function
  51134. æD pascal Boolean LockPixels(PixMapHandle pm)
  51135.     = {0x203C,0x0004,0x0001,0xAB1D}; 
  51136. æDT Boolean myVariable = LockPixels((PixMapHandle) pm);
  51137. æC 
  51138. These routines use PixMapHandles, and assume that the pixel maps were created by
  51139. OffscreenGWorld routines.  The GetPixBaseAddr and Pixmap32Bit routines can be
  51140. used on non-OffscreenGWorld PixMap records; the other routines won’t fail, but
  51141. they don’t return useful information.
  51142.  
  51143. FUNCTION LockPixels (pm: PixMapHandle): Boolean;
  51144.  
  51145. LockPixels must be called before drawing to or from an offscreen graphics world.
  51146. LockPixels locks down the offscreen buffer in memory for the time of the
  51147. drawing. 
  51148. If the offscreen buffer is purgeable and has indeed been purged, LockPixels
  51149. returns FALSE to signal that no drawing can be made to it. At that point, the
  51150. application should either call UpdateGWorld to reallocate it or draw directly in
  51151. the window it represents. 
  51152.  
  51153. If the offscreen buffer hasn’t been purged or is not purgeable, LockPixels
  51154. returns TRUE.
  51155.  
  51156. æKY UnlockPixels
  51157. æFc QDOffscreen.h
  51158. æT Function
  51159. æD pascal void UnlockPixels(PixMapHandle pm)
  51160.     = {0x203C,0x0004,0x0002,0xAB1D}; 
  51161. æDT UnlockPixels((PixMapHandle) pm);
  51162. æC 
  51163. As soon as the drawing is completed, UnlockPixels should be called. 
  51164.  
  51165.  
  51166. UnlockPixels unlocks the offscreen buffer. Call UnlockPixels as soon as the
  51167. application is finished drawing to or from the offscreen PixMap. You don’t need
  51168. to call UnlockPixels if LockPixels returned false, since LockPixels doesn’t lock
  51169. purged pixels. (However, calling UnlockPixels on purged pixels does no harm.) 
  51170.  
  51171. æKY UpdateGWorld
  51172. æFc QDOffscreen.h
  51173. æT Function
  51174. æD pascal GWorldFlags UpdateGWorld(GWorldPtr *offscreenGWorld,short pixelDepth,
  51175.     Rect *boundsRect,CTabHandle cTable,GDHandle aGDevice,GWorldFlags flags)
  51176.     = {0x203C,0x0016,0x0003,0xAB1D}; 
  51177. æDT GWorldFlags myVariable = UpdateGWorld((GWorldPtr *) offscreenGWorld,(short) pixelDepth,(
  51178.     Rect) * boundsRect,(CTabHandle) cTable,(GDHandle) aGDevice,(GWorldFlags) flags);
  51179. æC 
  51180. UpdateGWorld updates the offscreen graphics world described by offscreenGWorld
  51181. to the new boundsRect, pixelDepth, and cTable. BoundsRect, pixelDepth, and
  51182. cTable have the same meaning and work generally in the same way as in NewGWorld.
  51183.   
  51184. If pixelDepth is 0, the device list is rescanned to find the new deepest device
  51185. intersecting with the new boundsRect in global screen space.  
  51186. If the offscreen buffer has been purged, UpdateGWorld reallocates it.
  51187.  
  51188. If aGDevice is not NIL, the depth and color table of aGDevice are used instead
  51189. of pixelDepth and cTable.
  51190.  
  51191. The flags parameter can be nil or a combination of the flags clipPix, ditherPix,
  51192. and stretchPix, which are members of the GWorldFlags set. Some combinations are
  51193. illegal. The legal combinations are: 
  51194.  
  51195. clipPix
  51196. stretchPix
  51197. clipPix, ditherPix
  51198. stretchPix, ditherPix
  51199.  
  51200. If clipPix is set, the pixels are updated, with clipping if boundsRect has
  51201. changed.
  51202.  
  51203. If stretchPix is set, the pixels are updated, with stretching or shrinking if
  51204. boundsRect has changed. If boundsRect hasn’t changed, stretchPix is equivalent
  51205. to clipPix.
  51206.  
  51207. If ditherPix is set, the pixels are first updated according to the state of
  51208. clipPix or stretchPix. Then they are dithered if necessary.
  51209.  
  51210. If none of the flags is set, the pixels are not updated.
  51211.  
  51212. A pointer to the new offscreen graphics world is returned in offscreenGWorld. If
  51213. offscreenGWorld was the current GWorld and got changed by UpdateGWorld, the
  51214. current GWorld is set to the updated offscreenGWorld.
  51215.  
  51216. The result of UpdateGWorld will be a combination of the flags mapPix, newDepth,
  51217. alignPix, newRowBytes, reallocPix, clipPix, stretchPix, ditherPix, and
  51218. gwFlagErr, which are members of the GWorldFlags set. If gwFlagErr is set,
  51219. UpdateGWorld was unsuccessful and offscreenGWorld is left unchanged. The result
  51220. of UpdateGWorld should be type-cast to a LONGINT and contain one of the
  51221. following error codes:
  51222.  
  51223.   cDepthErr  Invalid pixel resolution
  51224.   paramErr  Illegal parameter
  51225.   plus other Memory Manager and QuickDraw errors.
  51226.  
  51227. If UpdateGWorld was successful, the other flags must be interpreted as follows:
  51228.  
  51229. Flag         Set if…
  51230. mapPix       Color table mapping occured.
  51231.  
  51232. newDepth     Pixels were scaled to a different depth.
  51233.  
  51234. alignPix     Pixels were realigned to the screen alignment.
  51235.  
  51236. newRowBytes  The PixMap was reconfigured in a new rowBytes.
  51237.  
  51238. reallocPix   The offscreen buffer had to be reallocated.
  51239.  
  51240. clipPix      The pixels were clipped.
  51241.  
  51242. stretchPix   Pixels were stretched or shrinked.
  51243.  
  51244. ditherPix    Pixels were dithered.
  51245.  
  51246. UpdateGWorld uses the following algorithm for pixel preservation:
  51247.  
  51248. 1.  If cTable is new, the pixels are mapped to the new color table.
  51249.  
  51250. 2.  If pixelDepth is new, the pixels are scaled to the new pixelDepth.
  51251.  
  51252. 3.  If boundsRect is new but has the same size, the PixMap is just realigned for
  51253. optimum CopyBits performance.
  51254.  
  51255. 4.  If boundsRect is smaller and clipPix is set, the pixels in the bottom and
  51256. right edges are clipped.
  51257.  
  51258. 5.  If boundsRect is bigger and clipPix is set, the bottom and right edges are
  51259. filled with the background color.
  51260.  
  51261. 6.  If boundsRect is smaller and stretchPix is set, the PixMap is reduced to the
  51262. new size.
  51263.  
  51264. 7.  If boundsRect is bigger and stretchPix is set, the PixMap is stretched to
  51265. the new size.
  51266.  
  51267. 8.  If the offscreen buffer was purged, it is reallocated but the pixels are
  51268. lost .
  51269.  
  51270. æKY DisposeGWorld
  51271. æFc QDOffscreen.h
  51272. æT Function
  51273. æD pascal void DisposeGWorld(const GWorldPtr *offscreenGWorld)
  51274.     = {0x203C,0x0004,0x0004,0xAB1D}; 
  51275. æDT DisposeGWorld((const GWorldPtr *) offscreenGWorld);
  51276. æC 
  51277. DisposeGWorld disposes of all the memory allocated for the offscreen port data
  51278. structure and substructures, offscreen PixMap and color table, offscreen buffer.
  51279. If an offscreen gdevice was created, it disposes of its GDevice structure and
  51280. substructures.  
  51281.  
  51282. Call DisposeGWorld only when the application no longer needs the offscreen
  51283. buffer. If the current device was the offscreen device attached to
  51284. offscreenGWorld, the current device is reset to MainDevice.  
  51285.  
  51286. æKY GetGWorld
  51287. æFc QDOffscreen.h
  51288. æT Function
  51289. æD pascal void GetGWorld(CGrafPtr *port,GDHandle *gdh)
  51290.     = {0x203C,0x0008,0x0005,0xAB1D}; 
  51291. æDT GetGWorld((CGrafPtr *) port,(GDHandle *) gdh);
  51292. æC 
  51293. GetGWorld returns in port and gdh the current graphics world. Port is set to the
  51294. current port, which can be a GrafPtr, CGrafPtr, or GWorldPtr. Gdh is set to the
  51295. current device.  
  51296.  
  51297. æKY SetGWorld
  51298. æFc QDOffscreen.h
  51299. æT Function
  51300. æD pascal void SetGWorld(CGrafPtr port,GDHandle gdh)
  51301.     = {0x203C,0x0008,0x0006,0xAB1D}; 
  51302. æDT SetGWorld((CGrafPtr) port,(GDHandle) gdh);
  51303. æC 
  51304. SetGWorld sets the current graphics world. SetGWorld can be used with port being
  51305. a GrafPtr, CGrafPtr, or GWorldPtr (with proper type-casting).  
  51306.  
  51307. If port is a GrafPtr or CGrafPtr, the current port is set to port and the
  51308. current device is set to gdh.  
  51309.  
  51310. If port is a GWorldPtr, the current port is set to port and the current device
  51311. is set to the device attached to the given graphics world. The gdh parameter is
  51312. ignored.  
  51313.  
  51314. æKY CTabChanged
  51315. æFc QDOffscreen.h
  51316. æT Function
  51317. æD pascal void CTabChanged(CTabHandle ctab)
  51318.     = {0x203C,0x0004,0x0007,0xAB1D}; 
  51319. æDT CTabChanged((CTabHandle) ctab);
  51320. æC 
  51321. Call CTabChanged after modifying the content of a color table. CTabChanged calls
  51322. GetCTSeed to get a new seed for the color table and notifies QuickDraw of the
  51323. change.
  51324.  
  51325. æKY PixPatChanged
  51326. æFc QDOffscreen.h
  51327. æT Function
  51328. æD pascal void PixPatChanged(PixPatHandle ppat)
  51329.     = {0x203C,0x0004,0x0008,0xAB1D}; 
  51330. æDT PixPatChanged((PixPatHandle) ppat);
  51331. æC 
  51332. Call PixPatChanged after modifying a PixPat data structure or any of its
  51333. substructures (patMap or patData records). PixPatChanged sets the patXValid flag
  51334. to -1 and notifies QuickDraw of the change.
  51335.  
  51336. If your application changes the pmTable field of the pixel pattern’s patMap, it
  51337. should call PixPatChanged. However, if your application changes the content of
  51338. the CLUT referenced by pmTable, it should call CTabChanged as well.
  51339.  
  51340. æKY PortChanged
  51341. æFc QDOffscreen.h
  51342. æT Function
  51343. æD pascal void PortChanged(GrafPtr port)
  51344.     = {0x203C,0x0004,0x0009,0xAB1D}; 
  51345. æDT PortChanged((GrafPtr) port);
  51346. æC 
  51347. Call PortChanged after modifying the content of a port or any of its
  51348. substructures. PortChanged notifies QuickDraw of the change.
  51349.  
  51350. None of the PixPat records pointed to by a CGrafPort record should be changed
  51351. directly. Use PenPixPat and BackPixPat instead. However, if your application
  51352. changes the content of one of the PixPat records, it should call PixPatChanged.
  51353.  
  51354. If your application changes the pmTable field of the port’s PixMap, it should
  51355. call PortChanged. However, if your application changes the content of the color
  51356. table referenced by pmTable, it should call CTabChanged as well.
  51357.  
  51358. æKY GDeviceChanged
  51359. æFc QDOffscreen.h
  51360. æT Function
  51361. æD pascal void GDeviceChanged(GDHandle gdh)
  51362.     = {0x203C,0x0004,0x000A,0xAB1D}; 
  51363. æDT GDeviceChanged((GDHandle) gdh);
  51364. æC 
  51365. Call GDeviceChanged after modifying a gDevice graphics device record or any of
  51366. its substructures. GDeviceChanged notifies QuickDraw of the change.
  51367.  
  51368. If your application changes the pmTable field of the graphics device record’s
  51369. PixMap, it should call GDeviceChanged. However, if your application changes the
  51370. content of the color table referenced by gdPMap, it should call CTabChanged as
  51371. well.
  51372.  
  51373. æKY AllowPurgePixels
  51374. æFc QDOffscreen.h
  51375. æT Function
  51376. æD pascal void AllowPurgePixels(PixMapHandle pm)
  51377.     = {0x203C,0x0004,0x000B,0xAB1D}; 
  51378. æDT AllowPurgePixels((PixMapHandle) pm);
  51379. æC 
  51380. AllowPurgePixels marks the PixMap’s offscreen buffer as purgeable. 
  51381.  
  51382. æKY NoPurgePixels
  51383. æFc QDOffscreen.h
  51384. æT Function
  51385. æD pascal void NoPurgePixels(PixMapHandle pm)
  51386.     = {0x203C,0x0004,0x000C,0xAB1D}; 
  51387. æDT NoPurgePixels((PixMapHandle) pm);
  51388. æC 
  51389. NoPurgePixels marks the PixMap’s offscreen buffer as unpurgeable.  
  51390.  
  51391. æKY GetPixelsState
  51392. æFc QDOffscreen.h
  51393. æT Function
  51394. æD pascal GWorldFlags GetPixelsState(PixMapHandle pm)
  51395.     = {0x203C,0x0004,0x000D,0xAB1D}; 
  51396. æDT GWorldFlags myVariable = GetPixelsState((PixMapHandle) pm);
  51397. æC 
  51398. GetPixelsState returns the state of the PixMap’s offscreen buffer. The state can
  51399. be a combination of the flags pixelsPurgeable and pixelsLocked, which are
  51400. members of the GWorldFlags set. GetPixelsState is used in conjunction with
  51401. SetPixelsState to save and restore the state of these flags. You can save the
  51402. flags, change any of them using one of the preceding routines, and then restore
  51403. their original state by passing the result of GetPixelsState back to the
  51404. SetPixelsState procedure. 
  51405.  
  51406. æKY SetPixelsState
  51407. æFc QDOffscreen.h
  51408. æT Function
  51409. æD pascal void SetPixelsState(PixMapHandle pm,GWorldFlags state)
  51410.     = {0x203C,0x0008,0x000E,0xAB1D}; 
  51411. æDT SetPixelsState((PixMapHandle) pm,(GWorldFlags) state);
  51412. æC 
  51413. SetPixelsState is used in conjunction with GetPixelsState; it sets the lock and
  51414. purge state of the PixMap’s offscreen buffer to the given flags by calling
  51415. LockPixels or UnlockPixels and AllowPurgePixels or NoPurgePixels.
  51416.  
  51417. æKY GetPixBaseAddr
  51418. æFc QDOffscreen.h
  51419. æT Function
  51420. æD pascal Ptr GetPixBaseAddr(PixMapHandle pm)
  51421.     = {0x203C,0x0004,0x000F,0xAB1D}; 
  51422. æDT Ptr myVariable = GetPixBaseAddr((PixMapHandle) pm);
  51423. æC 
  51424. GetPixBaseAddr returns a 32-bit pointer to the beginning of its pixels. This
  51425. pointer becomes invalid as soon as QuickDraw or the Toolbox gets called, unless
  51426. the pixels are locked and made unpurgeable with LockPixels and NoPurgePixels.  
  51427. GetPixBaseAddr should always be called before accessing the pixels of an
  51428. offscreen PixMap directly. Then the application should switch to 32-bit mode (if
  51429. it wasn’t in that mode already), access the pixels, and switch back to 24-bit
  51430. mode. The application should never access the baseAddr field of the PixMap
  51431. directly.  
  51432.  
  51433. If the offscreen buffer has been purged, GetPixBaseAddr returns NIL.  
  51434.  
  51435. If QuickDraw is called after GetPixBaseAddr, the contents of the offscreen
  51436. buffer are not guaranteed to be accurate unless GetPixBaseAddr is called again.
  51437.  
  51438. æKY NewScreenBuffer
  51439. æFc QDOffscreen.h
  51440. æT Function
  51441. æD pascal QDErr NewScreenBuffer(Rect *globalRect,Boolean purgeable,GDHandle *gdh,
  51442.     PixMapHandle *offscreenPixMap)
  51443.     = {0x203C,0x000E,0x0010,0xAB1D}; 
  51444. æDT QDErr myVariable = NewScreenBuffer((Rect *) globalRect,(Boolean) purgeable,(GDHandle *) gdh,(
  51445.     PixMapHandle) * offscreenPixMap);
  51446. æC 
  51447. NewScreenBuffer allocates an offscreen PixMap and offscreen buffer, using the
  51448. depth and color table of the deepest device intersecting with globalRect in
  51449. screen space. A handle to that device is returned in gdh and a handle to the
  51450. offscreen PixMap is returned in offscreenPixMap. If purgeable is true, the
  51451. offscreen buffer is made purgeable.  
  51452.  
  51453. Result codes
  51454. noErr        No error
  51455. cNoMemErr    Failed to allocate memory for structures
  51456. paramErr     Illegal parameter
  51457.  
  51458. LockPixels, UnlockPixels, AllowPurgePixels, NoPurgePixels, GetPixelsState,
  51459. SetPixelsState, and GetPixBaseAddr can all be called with offscreenPixMap as a
  51460. parameter.  
  51461.  
  51462. æKY DisposeScreenBuffer
  51463. æFc QDOffscreen.h
  51464. æT Function
  51465. æD pascal void DisposeScreenBuffer(PixMapHandle offscreenPixMap)
  51466.     = {0x203C,0x0004,0x0011,0xAB1D}; 
  51467. æDT DisposeScreenBuffer((PixMapHandle) offscreenPixMap);
  51468. æC 
  51469. DisposeScreenBuffer is called by DisposeGWorld. It disposes of the memory
  51470. allocated for the offscreen buffer, offscreen PixMap and color table.  
  51471.  
  51472. æKY GetGWorldDevice
  51473. æFc QDOffscreen.h
  51474. æT Function
  51475. æD 
  51476. pascal GDHandle GetGWorldDevice(const GWorldPtr *offscreenGWorld)
  51477.     = {0x203C,0x0004,0x0012,0xAB1D}; 
  51478. æDT GDHandle myVariable = GetGWorldDevice((const GWorldPtr *) offscreenGWorld);
  51479. æC 
  51480. GetGWorldDevice returns a handle to the device attached to the offscreenGWorld.
  51481. This device is generally the offscreen device created by NewGWorld. If
  51482. offscreenGWorld was created with the noNewDevice flag set, the attached device
  51483. is one of the screen devices or the device passed to NewGWorld or UpdateGWorld.
  51484.  
  51485. If offscreenGWorld is not a GWorld (for example, a regular GrafPort or 
  51486. CGrafPort), GetGWorldDevice returns the current device.  
  51487.  
  51488. æKY QDDone
  51489. æFc QDOffscreen.h
  51490. æT Function
  51491. æD pascal Boolean QDDone(GrafPtr port)
  51492.     = {0x203C,0x0004,0x0013,0xAB1D}; 
  51493. æDT Boolean myVariable = QDDone((GrafPtr) port);
  51494. æC 
  51495. The QDDone function returns true if drawing operations have completed in the
  51496. designated port, false if any remain to be executed.  This call may be useful if
  51497. a graphics accelerator is present and operating asynchronously.  You can ensure
  51498. that all drawing has been done and avoid the possibility that new drawing
  51499. operations might be overlaid by previously issued but unexecuted operations.
  51500.  
  51501. æKY OffscreenVersion
  51502. æFc QDOffscreen.h
  51503. æT Function
  51504. æD pascal long OffscreenVersion(void)
  51505.     = {0x203C,0x0000,0x0014,0xAB1D}; 
  51506. æDT long myVariable = OffscreenVersion()(void);
  51507. æC 
  51508.  
  51509. æKY NewTempScreenBuffer
  51510. æFc QDOffscreen.h
  51511. æT Function
  51512. æD pascal QDErr NewTempScreenBuffer(Rect *globalRect,Boolean purgeable,GDHandle *gdh,
  51513.     pixMapHandle *offscreenPixMap)
  51514.     = {0x203C,0x000E,0x0015,0xAB1D}; 
  51515. æDT QDErr myVariable = NewTempScreenBuffer((Rect *) globalRect,(Boolean) purgeable,(GDHandle *) gdh,(
  51516.     pixMapHandle) * offscreenPixMap);
  51517. æC 
  51518. NewTempScreenBuffer performs the same functions as NewScreenBuffer except that
  51519. it will allocate pixels in MultiFinder temporary memory.
  51520.  
  51521. æKY Pixmap32Bit
  51522. æFc QDOffscreen.h
  51523. æT Function
  51524. æD pascal Boolean Pixmap32Bit(PixMapHandle offscreenPixMap)
  51525.     = {0x203C,0x0004,0x0016,0xAB1D}; 
  51526. æDT Boolean myVariable = Pixmap32Bit((PixMapHandle) offscreenPixMap);
  51527. æC 
  51528. Pixmap32Bit returns TRUE if the specified PixMap requires 32-bit addressing mode
  51529. for access to its pixels.
  51530.  
  51531.  
  51532. æKY GetGWorldPixMap
  51533. æFc QDOffscreen.h
  51534. æT Function
  51535. æD pascal PixMapHandle GetGWorldPixMap(const GWorldPtr *offscreenGWorld)
  51536.     = {0x203C,0x0004,0x0017,0xAB1D}; 
  51537. æDT PixMapHandle myVariable = GetGWorldPixMap((const GWorldPtr *) offscreenGWorld);
  51538. æC 
  51539.  
  51540.  
  51541. æKY Quickdraw.h
  51542. æKL AddComp
  51543. addpt
  51544. AddPt
  51545. AddSearch
  51546. AllocCursor
  51547. BackColor
  51548. BackPat
  51549. BackPixPat
  51550. BitMapToRegion
  51551. CalcCMask
  51552. CalcMask
  51553. CharExtra
  51554. CharWidth
  51555. ClipRect
  51556. CloseCPort
  51557. ClosePicture
  51558. ClosePoly
  51559. ClosePort
  51560. CloseRgn
  51561. Color2Index
  51562. ColorBit
  51563. CopyBits
  51564. CopyMask
  51565. CopyPixMap
  51566. CopyPixPat
  51567. CopyRgn
  51568. DelComp
  51569. DelSearch
  51570. DiffRgn
  51571. DisposCCursor
  51572. DisposCIcon
  51573. DisposCTable
  51574. DisposeRgn
  51575. DisposGDevice
  51576. DisposPixMap
  51577. DisposPixPat
  51578. DrawChar
  51579. DrawPicture
  51580. drawstring
  51581. DrawString
  51582. DrawText
  51583. EmptyRect
  51584. EmptyRgn
  51585. EqualPt
  51586. equalpt
  51587. EqualRect
  51588. EqualRgn
  51589. EraseArc
  51590. EraseOval
  51591. ErasePoly
  51592. EraseRect
  51593. EraseRgn
  51594. EraseRoundRect
  51595. FillArc
  51596. FillCArc
  51597. FillCOval
  51598. FillCPoly
  51599. FillCRect
  51600. FillCRgn
  51601. FillCRoundRect
  51602. FillOval
  51603. FillPoly
  51604. FillRect
  51605. FillRgn
  51606. FillRoundRect
  51607. ForeColor
  51608. FrameArc
  51609. FrameOval
  51610. FramePoly
  51611. FrameRect
  51612. FrameRgn
  51613. FrameRoundRect
  51614. GetBackColor
  51615. GetCCursor
  51616. GetCIcon
  51617. GetClip
  51618. GetCPixel
  51619. GetCTable
  51620. GetCTSeed
  51621. GetDeviceList
  51622. GetFontInfo
  51623. GetForeColor
  51624. GetGDevice
  51625. GetMainDevice
  51626. GetMaskTable
  51627. GetMaxDevice
  51628. GetNextDevice
  51629. GetPen
  51630. GetPenState
  51631. GetPixel
  51632. GetPixPat
  51633. GetPort
  51634. GetSubTable
  51635. GlobalToLocal
  51636. GrafDevice
  51637. HideCursor
  51638. HidePen
  51639. HiliteColor
  51640. Index2Color
  51641. InitCPort
  51642. InitCursor
  51643. InitGDevice
  51644. InitGraf
  51645. InitPort
  51646. InsetRect
  51647. InsetRgn
  51648. InvertArc
  51649. InvertColor
  51650. InvertOval
  51651. InvertPoly
  51652. InvertRect
  51653. InvertRgn
  51654. InvertRoundRect
  51655. KillPicture
  51656. KillPoly
  51657. Line
  51658. LineTo
  51659. LocalToGlobal
  51660. MakeITable
  51661. MakeRGBPat
  51662. MapPoly
  51663. MapPt
  51664. MapRect
  51665. MapRgn
  51666. MeasureText
  51667. Move
  51668. MovePortTo
  51669. MoveTo
  51670. NewGDevice
  51671. NewPixMap
  51672. NewPixPat
  51673. NewRgn
  51674. ObscureCursor
  51675. OffsetPoly
  51676. OffsetRect
  51677. OffsetRgn
  51678. OpColor
  51679. OpenCPort
  51680. OpenPicture
  51681. OpenPoly
  51682. OpenPort
  51683. OpenRgn
  51684. PaintArc
  51685. PaintOval
  51686. PaintPoly
  51687. PaintRect
  51688. PaintRgn
  51689. PaintRoundRect
  51690. PenMode
  51691. PenNormal
  51692. PenPat
  51693. PenPixPat
  51694. PenSize
  51695. PicComment
  51696. PlotCIcon
  51697. PortSize
  51698. ProtectEntry
  51699. Pt2Rect
  51700. pt2rect
  51701. PtInRect
  51702. ptinrect
  51703. ptinrgn
  51704. PtInRgn
  51705. pttoangle
  51706. PtToAngle
  51707. QDError
  51708. Random
  51709. RealColor
  51710. RectInRgn
  51711. RectRgn
  51712. ReserveEntry
  51713. RestoreEntries
  51714. RGBBackColor
  51715. RGBForeColor
  51716. SaveEntries
  51717. ScalePt
  51718. ScrollRect
  51719. SectRect
  51720. SectRgn
  51721. SeedCFill
  51722. SeedFill
  51723. SetCCursor
  51724. SetClientID
  51725. SetClip
  51726. SetCPixel
  51727. SetCursor
  51728. SetDeviceAttribute
  51729. SetEmptyRgn
  51730. SetEntries
  51731. SetGDevice
  51732. SetOrigin
  51733. SetPenState
  51734. SetPort
  51735. SetPortBits
  51736. SetPortPix
  51737. SetPt
  51738. SetRect
  51739. SetRectRgn
  51740. SetStdCProcs
  51741. SetStdProcs
  51742. ShowCursor
  51743. ShowPen
  51744. SpaceExtra
  51745. StdArc
  51746. StdBits
  51747. StdComment
  51748. StdGetPic
  51749. stdline
  51750. StdLine
  51751. StdOval
  51752. StdPoly
  51753. StdPutPic
  51754. StdRect
  51755. StdRgn
  51756. StdRRect
  51757. stdtext
  51758. StdText
  51759. StdTxMeas
  51760. stringwidth
  51761. StringWidth
  51762. StuffHex
  51763. stuffhex
  51764. subpt
  51765. SubPt
  51766. TestDeviceAttribute
  51767. TextFace
  51768. TextFont
  51769. TextMode
  51770. TextSize
  51771. TextWidth
  51772. UnionRect
  51773. UnionRgn
  51774. XorRgn
  51775.  
  51776. addMax
  51777. addOver
  51778. addPin
  51779. adMax
  51780. adMin
  51781. allInit
  51782. BitMap
  51783. BitMapHandle
  51784. BitMapPtr
  51785. Bits16[16]
  51786. blackBit
  51787. blackColor
  51788. blend
  51789. blueBit
  51790. blueColor
  51791. bold
  51792. CCrsr
  51793. CCrsrHandle
  51794. CCrsrPtr
  51795. CGrafPort
  51796. CGrafPtr
  51797. chunky
  51798. chunkyPlanar
  51799. CIcon
  51800. CIconHandle
  51801. CIconPtr
  51802. clutType
  51803. ColorSpec
  51804. ColorTable
  51805. condense
  51806. CProcHndl
  51807. CProcPtr
  51808. CProcRec
  51809. CQDProcs
  51810. CQDProcsPtr
  51811. CTabHandle
  51812. CTabPtr
  51813. CursHandle
  51814. Cursor
  51815. CursPtr
  51816. cyanBit
  51817. cyanColor
  51818. defQDColors
  51819. directType
  51820. erase
  51821. extend
  51822. fill
  51823. fixedType
  51824. FontInfo
  51825. frame
  51826. GammaTbl
  51827. GammaTblHandle
  51828. GammaTblPtr
  51829. gdDevType
  51830. GDevice
  51831. GDHandle
  51832. GDPtr
  51833. GrafPort
  51834. GrafPtr
  51835. GrafVars
  51836. GrafVerb
  51837. greenBit
  51838. greenColor
  51839. GVarHandle
  51840. GVarPtr
  51841. hiliteBit
  51842. invalColReq
  51843. inverseBit
  51844. invert
  51845. ITab
  51846. ITabHandle
  51847. ITabPtr
  51848. italic
  51849. magentaBit
  51850. magentaColor
  51851. mainScreen
  51852. MatchRec
  51853. noDriver
  51854. normal
  51855. normalBit
  51856. notPatBic
  51857. notPatCopy
  51858. notPatOr
  51859. notPatXor
  51860. notSrcBic
  51861. notSrcCopy
  51862. notSrcOr
  51863. notSrcXor
  51864. outline
  51865. paint
  51866. patBic
  51867. patCopy
  51868. patOr
  51869. Pattern[8]
  51870. patXor
  51871. PenState
  51872. pHiliteBit
  51873. PicHandle
  51874. picLParen
  51875. PicPtr
  51876. picRParen
  51877. Picture
  51878. PixelType
  51879. PixMap
  51880. PixMapHandle
  51881. PixMapPtr
  51882. PixPat
  51883. PixPatHandle
  51884. PixPatPtr
  51885. planar
  51886. Polygon
  51887. PolyHandle
  51888. PolyPtr
  51889. qd
  51890. QDByte
  51891. QDErr
  51892. QDProcs
  51893. QDProcsPtr
  51894. ramInit
  51895. redBit
  51896. redColor
  51897. Region
  51898. ReqListRec
  51899. RGBColor
  51900. RgnHandle
  51901. RgnPtr
  51902. screenActive
  51903. screenDevice
  51904. shadow
  51905. SProcHndl
  51906. SProcPtr
  51907. SProcRec
  51908. srcBic
  51909. srcCopy
  51910. srcOr
  51911. srcXor
  51912. subOver
  51913. subPin
  51914. transparent
  51915. underline
  51916. whiteColor
  51917. yellowBit
  51918. yellowColor
  51919.  
  51920. æKY invalColReq
  51921. æFc Quickdraw.h
  51922. æT #define
  51923. æD #define invalColReq -1 /*invalid color table request*/
  51924. æC 
  51925.  
  51926. æKY srcCopy
  51927. æFc Quickdraw.h
  51928. æT #define
  51929. æD #define srcCopy 0 /*the 16 transfer modes*/
  51930. æC 
  51931.  
  51932. æKY srcOr
  51933. æFc Quickdraw.h
  51934. æT #define
  51935. æD #define srcOr 1
  51936. æC 
  51937.  
  51938. æKY srcXor
  51939. æFc Quickdraw.h
  51940. æT #define
  51941. æD #define srcXor 2
  51942. æC 
  51943.  
  51944. æKY srcBic
  51945. æFc Quickdraw.h
  51946. æT #define
  51947. æD #define srcBic 3
  51948. æC 
  51949.  
  51950. æKY notSrcCopy
  51951. æFc Quickdraw.h
  51952. æT #define
  51953. æD #define notSrcCopy 4
  51954. æC 
  51955.  
  51956. æKY notSrcOr
  51957. æFc Quickdraw.h
  51958. æT #define
  51959. æD #define notSrcOr 5
  51960. æC 
  51961.  
  51962. æKY notSrcXor
  51963. æFc Quickdraw.h
  51964. æT #define
  51965. æD #define notSrcXor 6
  51966. æC 
  51967.  
  51968. æKY notSrcBic
  51969. æFc Quickdraw.h
  51970. æT #define
  51971. æD #define notSrcBic 7
  51972. æC 
  51973.  
  51974. æKY patCopy
  51975. æFc Quickdraw.h
  51976. æT #define
  51977. æD #define patCopy 8
  51978. æC 
  51979.   /* Pattern transfer modes */
  51980.  
  51981. #define  patCopy      8
  51982. #define  patOr        9
  51983. #define  patXor       10
  51984. #define  patBic       11
  51985. #define  notPatCopy   12
  51986. #define  notPatOr     13
  51987. #define  notPatXor    14
  51988. #define  notPatBic    15
  51989.  
  51990. æKY patOr
  51991. æFc Quickdraw.h
  51992. æT #define
  51993. æD #define patOr 9
  51994. æC 
  51995.  
  51996. æKY patXor
  51997. æFc Quickdraw.h
  51998. æT #define
  51999. æD #define patXor 10
  52000. æC 
  52001.  
  52002. æKY patBic
  52003. æFc Quickdraw.h
  52004. æT #define
  52005. æD #define patBic 11
  52006. æC 
  52007.  
  52008. æKY notPatCopy
  52009. æFc Quickdraw.h
  52010. æT #define
  52011. æD #define notPatCopy 12
  52012. æC 
  52013.  
  52014. æKY notPatOr
  52015. æFc Quickdraw.h
  52016. æT #define
  52017. æD #define notPatOr 13
  52018. æC 
  52019.  
  52020. æKY notPatXor
  52021. æFc Quickdraw.h
  52022. æT #define
  52023. æD #define notPatXor 14
  52024. æC 
  52025.  
  52026. æKY notPatBic
  52027. æFc Quickdraw.h
  52028. æT #define
  52029. æD #define notPatBic 15
  52030. æC 
  52031.  
  52032. æKY blend
  52033. æFc Quickdraw.h
  52034. æT #define
  52035. æD 
  52036. /* Arithmetic transfer modes */
  52037.  
  52038. #define blend 32
  52039. æC 
  52040.  
  52041. æKY addPin
  52042. æFc Quickdraw.h
  52043. æT #define
  52044. æD #define addPin 33
  52045. æC 
  52046.  
  52047. æKY addOver
  52048. æFc Quickdraw.h
  52049. æT #define
  52050. æD #define addOver 34
  52051. æC 
  52052.  
  52053. æKY subPin
  52054. æFc Quickdraw.h
  52055. æT #define
  52056. æD #define subPin 35
  52057. æC 
  52058.  
  52059. æKY addMax
  52060. æFc Quickdraw.h
  52061. æT #define
  52062. æD #define addMax 37
  52063. æC _______________________________________________________________________________
  52064.  
  52065. »Arithmetic Drawing Modes
  52066.  
  52067. Color QuickDraw uses a set of arithmetic drawing modes designed specifically for use
  52068. with color. These modes change the destination pixels by performing arithmetic operations
  52069. on the source and destination pixels. These drawing modes are most useful in 8-bit
  52070. color, but work on 4-bit and 2-bit color as well. If the destination bitmap is one
  52071. bit deep, the mode reverts to one of the old transfer modes that approximates the
  52072. arithmetic mode requested.
  52073.  
  52074. Each drawing routine converts the source and destination pixels to their RGB components,
  52075. performs an operation on each pair of components to provide a new RGB value for the
  52076. destination, and then assigns the destination a pixel value close to the calculated
  52077. RGB value. The arithmetic modes listed below can be used for all drawing operations;
  52078. your application can pass them as a parameter to TextMode, PenMode, or CopyBits.
  52079.  
  52080. addOver    This mode assigns to the destination pixel the color closest to
  52081.            the sum of the source and destination RGB values. If the sum of
  52082.            any of the RGB components exceeds the maximum allowable value,
  52083.            65,535, the RGB value wraps around to the value less 65,536.
  52084.            AddOver is slightly faster than addPin. If the destination bitmap
  52085.            is one bit deep, addOver reverts to Xor.
  52086.  
  52087. addPin     This mode assigns to the destination pixel the color closest to
  52088.            the sum of the destination RGB values, pinned to a maximum allowable
  52089.            RGB value. For grafPorts, the pin value is always white. For
  52090.            cGrafPorts, the pin value is assigned using OpColor. If the
  52091.            destination bitmap is one bit deep, addPin reverts to Bic.
  52092.  
  52093. subOver    This mode assigns to the destination pixel the color closest to
  52094.            the difference of the source and destination RGB values. If the
  52095.            result is less than 0, the RGB value wraps around to 65,536 less
  52096.            the result. SubOver is slightly faster than subPin. If the
  52097.            destination bitmap is one bit deep, subOver reverts to Xor.
  52098.  
  52099. subPin     This mode assigns to the destination pixel the color closest to
  52100.            the difference of the sum and the destination RGB values, pinned
  52101.            to a minimum allowable RGB value. For grafPorts, the pin value is
  52102.            always black. In a cGrafPort, the pin value is assigned by using
  52103.            OpColor. If the destination bitmap is one bit deep, subPin reverts
  52104.            to Or.
  52105.  
  52106. adMax      (Arithmetic Drawing Max) This mode compares the source and
  52107.            destination pixels, and replaces the destination pixel with the
  52108.            color containing the greater saturation of each of the RGB
  52109.            components. Each RGB component comparison is done independently,
  52110.            so the resulting color isn’t necessarily either the source or the
  52111.            destination color. If the destination bitmap is one bit deep,
  52112.            adMax reverts to Bic.
  52113.  
  52114. adMin      (Arithmetic Drawing Min) This mode compares the source and
  52115.            destination pixels, and replaces the destination pixel with
  52116.            the color containing the lesser saturation of each of the RGB
  52117.            components. Each RGB component is compared independently, so
  52118.            the resulting color isn’t necessarily the source or the
  52119.            destination color. If the destination bitmap is one bit deep,
  52120.            adMin reverts to Or.
  52121.  
  52122. blend      This mode replaces the destination pixel with a weighted average
  52123.            of the colors of the source and destination pixels. The formula
  52124.            used to calculate the destination is:
  52125.  
  52126.              dest = source*weight/65,536 + destination*(1-weight/65,536)
  52127.  
  52128.            where weight is an unsigned value between 1 and 65,535. In a
  52129.            grafPort, the weight is set to 50% gray, so that equal weights
  52130.            of the source and destination RGB components are combined to
  52131.            produce the destination color. In a cGrafPort, the weight is an
  52132.            RGBColor that individually specifies the weights of the red,
  52133.            green, and blue components. The weight is assigned using OpColor.
  52134.            If the destination bitmap is one bit deep, blend reverts to Copy.
  52135.  
  52136. Because drawing with the arithmetic modes uses the closest matching pixel values, and
  52137. not necessarily exact matches, these modes might not produce the results you expect.
  52138. For instance, suppose srcCopy mode is used to paint a green pixel on the screen in
  52139. 4-bit mode. Of the 16 colors available, the closest green may contain a small amount
  52140. of red, as in RGB components of 300 red, 65,535 green, and 0 blue. AddOver is then
  52141. used to paint a red pixel on top of the green pixel, ideally resulting in a yellow
  52142. pixel. The red pixel’s RGB components are 65,535 red, 0 green, and 0 blue. Adding the
  52143. red components together wraps to 300, since the largest representable value is 65,535.
  52144. In this case, AddOver would cause no visible change at all. Using AddPin with an
  52145. opColor of white would produce the desired results.
  52146.  
  52147. On the Macintosh II the rules for setting the pen mode and the text mode have been
  52148. relaxed slightly. It’s no longer necessary to specify a pattern mode or a source mode
  52149. (patCopy as opposed to srcCopy) to perform a particular operation. QuickDraw will
  52150. choose the correct drawing mode automatically. However, to be compatible with earlier
  52151. versions of QuickDraw, you application must specify the correct drawing mode. Text
  52152. and bitmaps should always use a source mode; rectangles, regions, polygons, arcs,
  52153. ovals, round rectangles, and lines should always use a pattern mode.
  52154.  
  52155. The constants used for the arithmetic transfer modes are as follows:
  52156.  
  52157. CONST
  52158.  blend      = 32;
  52159.  addPin     = 33;
  52160.  addOver    = 34;
  52161.  subPin     = 35;
  52162.  adMax      = 37;
  52163.  subOver    = 38;
  52164.  adMin      = 39;
  52165.  
  52166. Warning:  Unlike the rest of QuickDraw, the arithmetic modes don’t call the
  52167.           Color Manager when mapping a requested RGB value to a pixel value.
  52168.           If your application replaces the color matching routines, you must
  52169.           either not use these modes, or you must maintain the inverse table
  52170.           using the Color Manager routines.
  52171.  
  52172. æKY adMax
  52173. æFc Quickdraw.h
  52174. æT #define
  52175. æD #define adMax 37
  52176. æC 
  52177.  
  52178. æKY subOver
  52179. æFc Quickdraw.h
  52180. æT #define
  52181. æD #define subOver 38
  52182. æC 
  52183.  
  52184. æKY adMin
  52185. æFc Quickdraw.h
  52186. æT #define
  52187. æD #define adMin 39
  52188. æC 
  52189.  
  52190. æKY transparent
  52191. æFc Quickdraw.h
  52192. æT #define
  52193. æD 
  52194. /* Transparent mode constant */
  52195.  
  52196. #define transparent 36
  52197. æC _______________________________________________________________________________
  52198.  
  52199. »Replace with Transparency
  52200.  
  52201. The transparent mode replaces the destination pixel with the source pixel if the
  52202. source pixel isn’t equal to the background color. This mode is most useful in 8-bit,
  52203. 4-bit, or 2-bit color modes. To specify a transparent pattern, use the drawing mode
  52204. transparent+patCopy. If the destination pixMap is one bit deep, the mode is translated
  52205. to Or. Transparency can be specified as a parameter to TextMode, PenMode, or CopyBits.
  52206.  
  52207. Transparent mode is optimized to handle source bitmaps with large transparent holes,
  52208. as an alternative to specifying an unusual clipping region or mask parameter to
  52209. CopyMask. Patterns aren’t optimized, and may not draw as quickly.
  52210.  
  52211. The constant used for transparent mode is
  52212.  
  52213. CONST
  52214.  transparent     = 36;
  52215.  
  52216. æKY normalBit
  52217. æFc Quickdraw.h
  52218. æT #define
  52219. æD 
  52220. /* QuickDraw color separation constants
  52221.  
  52222.  */
  52223.  
  52224. #define normalBit 0 /*normal screen mapping*/
  52225. æC 
  52226.  
  52227. æKY inverseBit
  52228. æFc Quickdraw.h
  52229. æT #define
  52230. æD #define inverseBit 1 /*inverse screen mapping*/
  52231. æC 
  52232.  
  52233. æKY redBit
  52234. æFc Quickdraw.h
  52235. æT #define
  52236. æD #define redBit 4 /*RGB additive mapping*/
  52237. æC 
  52238.  
  52239. æKY greenBit
  52240. æFc Quickdraw.h
  52241. æT #define
  52242. æD #define greenBit 3
  52243. æC 
  52244.  
  52245. æKY blueBit
  52246. æFc Quickdraw.h
  52247. æT #define
  52248. æD #define blueBit 2
  52249. æC 
  52250.  
  52251. æKY cyanBit
  52252. æFc Quickdraw.h
  52253. æT #define
  52254. æD #define cyanBit 8 /*CMYBk subtractive mapping*/
  52255. æC 
  52256.  
  52257. æKY magentaBit
  52258. æFc Quickdraw.h
  52259. æT #define
  52260. æD #define magentaBit 7
  52261. æC 
  52262.  
  52263. æKY yellowBit
  52264. æFc Quickdraw.h
  52265. æT #define
  52266. æD #define yellowBit 6
  52267. æC 
  52268.  
  52269. æKY blackBit
  52270. æFc Quickdraw.h
  52271. æT #define
  52272. æD #define blackBit 5
  52273. æC 
  52274.  
  52275. æKY blackColor
  52276. æFc Quickdraw.h
  52277. æT #define
  52278. æD #define blackColor 33 /*colors expressed in these mappings*/
  52279. æC 
  52280. _______________________________________________________________________________
  52281.  
  52282. »Drawing Color in a GrafPort
  52283.  
  52284. Although the QuickDraw graphics routines were designed mainly for monochrome drawing,
  52285. they also included some rudimentary color capabilities. A pair of fields in the
  52286. grafPort record, fgColor and bkColor, allow a foreground and background color to be
  52287. specified. The color values used in these fields are based on a planar model: each
  52288. bit position corresponds to a different color plane, and the value of each bit indicates
  52289. whether a particular color plane should be activated. (The term color plane refers to
  52290. a logical plane, rather than a physical plane.) The individual color planes combine
  52291. to produce the
  52292. full-color image.
  52293.  
  52294. The standard QuickDraw color values consist of one bit for normal monochrome drawing
  52295. (black on white), one bit for inverted monochrome (white on black), three bits for
  52296. the additive primary colors (red, green, blue) used in video display, and four bits
  52297. for the subtractive primary colors (cyan, magenta, yellow, black) used in hardcopy
  52298. printing. The original QuickDraw interface includes a set of predefined constants for
  52299. the standard colors:
  52300.  
  52301. CONST
  52302.   blackColor   = 33;
  52303.   whiteColor   = 30;
  52304.   redColor     = 209;
  52305.   greenColor   = 329;
  52306.   blueColor    = 389;
  52307.   cyanColor    = 269;
  52308.   magentaColor = 149;
  52309.   yellowColor  = 89;
  52310.  
  52311. These are the only colors available in the original QuickDraw. All programs that draw
  52312. into grafPorts are limited to these eight colors. When these colors are drawn to the
  52313. screen on the Macintosh II, Color QuickDraw automatically draws them in color, if the
  52314. screen is set to a color mode.
  52315.  
  52316. æKY whiteColor
  52317. æFc Quickdraw.h
  52318. æT #define
  52319. æD #define whiteColor 30
  52320. æC 
  52321.  
  52322. æKY redColor
  52323. æFc Quickdraw.h
  52324. æT #define
  52325. æD #define redColor 205
  52326. æC 
  52327.  
  52328. æKY greenColor
  52329. æFc Quickdraw.h
  52330. æT #define
  52331. æD #define greenColor 341
  52332. æC 
  52333.  
  52334. æKY blueColor
  52335. æFc Quickdraw.h
  52336. æT #define
  52337. æD #define blueColor 409
  52338. æC 
  52339.  
  52340. æKY cyanColor
  52341. æFc Quickdraw.h
  52342. æT #define
  52343. æD #define cyanColor 273
  52344. æC 
  52345.  
  52346. æKY magentaColor
  52347. æFc Quickdraw.h
  52348. æT #define
  52349. æD #define magentaColor 137
  52350. æC 
  52351.  
  52352. æKY yellowColor
  52353. æFc Quickdraw.h
  52354. æT #define
  52355. æD #define yellowColor 69
  52356. æC 
  52357.  
  52358. æKY picLParen
  52359. æFc Quickdraw.h
  52360. æT #define
  52361. æD #define picLParen 0 /*standard picture comments*/
  52362. æC 
  52363.  
  52364. æKY picRParen
  52365. æFc Quickdraw.h
  52366. æT #define
  52367. æD #define picRParen 1
  52368. æC 
  52369.  
  52370. æKY normal
  52371. æFc Quickdraw.h
  52372. æT #define
  52373. æD #define normal 0
  52374. æC 
  52375.  
  52376. æKY bold
  52377. æFc Quickdraw.h
  52378. æT #define
  52379. æD #define bold 1
  52380. æC 
  52381.  
  52382. æKY italic
  52383. æFc Quickdraw.h
  52384. æT #define
  52385. æD #define italic 2
  52386. æC 
  52387.  
  52388. æKY underline
  52389. æFc Quickdraw.h
  52390. æT #define
  52391. æD #define underline 4
  52392. æC 
  52393.  
  52394. æKY outline
  52395. æFc Quickdraw.h
  52396. æT #define
  52397. æD #define outline 8
  52398. æC 
  52399.  
  52400. æKY shadow
  52401. æFc Quickdraw.h
  52402. æT #define
  52403. æD #define shadow 0x10
  52404. æC 
  52405.  
  52406. æKY condense
  52407. æFc Quickdraw.h
  52408. æT #define
  52409. æD #define condense 0x20
  52410. æC 
  52411.  
  52412. æKY extend
  52413. æFc Quickdraw.h
  52414. æT #define
  52415. æD #define extend 0x40
  52416. æC 
  52417.  
  52418. æKY clutType
  52419. æFc Quickdraw.h
  52420. æT #define
  52421. æD #define clutType 0 /*0 if lookup table*/
  52422. æC 
  52423.  
  52424. æKY fixedType
  52425. æFc Quickdraw.h
  52426. æT #define
  52427. æD #define fixedType 1 /*1 if fixed table*/
  52428. æC 
  52429.  
  52430. æKY directType
  52431. æFc Quickdraw.h
  52432. æT #define
  52433. æD #define directType 2 /*2 if direct values*/
  52434. æC 
  52435.  
  52436. æKY gdDevType
  52437. æFc Quickdraw.h
  52438. æT #define
  52439. æD #define gdDevType 0 /*0 = monochrome 1 = color*/
  52440. æC 
  52441.  
  52442. æKY ramInit
  52443. æFc Quickdraw.h
  52444. æT #define
  52445. æD #define ramInit 10 /*1 if initialized from 'scrn' resource*/
  52446. æC 
  52447.  
  52448. æKY mainScreen
  52449. æFc Quickdraw.h
  52450. æT #define
  52451. æD #define mainScreen 11 /* 1 if main screen */
  52452. æC 
  52453.  
  52454. æKY allInit
  52455. æFc Quickdraw.h
  52456. æT #define
  52457. æD #define allInit 12 /* 1 if all devices initialized */
  52458. æC 
  52459.  
  52460. æKY screenDevice
  52461. æFc Quickdraw.h
  52462. æT #define
  52463. æD #define screenDevice 13 /*1 if screen device [not used]*/
  52464. æC 
  52465.  
  52466. æKY noDriver
  52467. æFc Quickdraw.h
  52468. æT #define
  52469. æD #define noDriver 14 /* 1 if no driver for this GDevice */
  52470. æC 
  52471.  
  52472. æKY screenActive
  52473. æFc Quickdraw.h
  52474. æT #define
  52475. æD #define screenActive 15 /*1 if in use*/
  52476. æC 
  52477.  
  52478. æKY hiliteBit
  52479. æFc Quickdraw.h
  52480. æT #define
  52481. æD #define hiliteBit 7 /*flag bit in HiliteMode (lowMem flag)*/
  52482. æC _______________________________________________________________________________
  52483.  
  52484. »The Hilite Mode
  52485.  
  52486. This new method of highlighting exchanges the background color and the highlight
  52487. color in the destination. This has the visual effect of using a highlighting pen to
  52488. select the object. For instance, TextEdit uses the hilite mode to select text: if the
  52489. highlight color is yellow, selected text appears on a yellow background. In general,
  52490. highlighting should be used in place of inversion when selecting and deselecting
  52491. objects such as text or graphics.
  52492.  
  52493. There are two ways to use hilite mode. The easiest is to call
  52494.  
  52495.   BitClr (Ptr(HiliteMode,pHiliteBit));
  52496.  
  52497. just before calling InvertRect, InvertRgn, InvertArc, InvertRoundRct, or InvertPoly
  52498. or any drawing using srcXor mode. On a one-bit-deep destination, this will work
  52499. exactly like inversion, and is compatible with all versions of QuickDraw. Color
  52500. QuickDraw resets the hilite bit after performing each drawing operation, so the
  52501. hilite bit should be cleared immediately before calling a routine that is to do
  52502. highlighting. Routines that formerly used Xor inversion, such as the Invert routines,
  52503. Paint, Frame, LineTo, text drawing, and CopyBits, will now use hilite mode if the
  52504. hilite bit is clear.
  52505.  
  52506. Assembly language note:  You can use
  52507.  
  52508.                            BCLR #hiliteBit, hiliteMode
  52509.  
  52510.                          Do not alter the other bits in HiliteMode.
  52511.  
  52512. The second way to use hilite mode is to pass it directly to TextMode, PenMode, or
  52513. CopyBits as a parameter.
  52514.  
  52515. Hilite mode uses the source or pattern to decide which bits to exchange; only bits
  52516. that are on in the source or pattern can be highlighted in the destination.
  52517.  
  52518. A very small inversion should probably not use hilite mode, because a small selection
  52519. in the hilite color might be too hard to see. TextEdit, for instance, uses hilite
  52520. mode to select and deselect text, but not to blink the insertion point.
  52521.  
  52522. Hilite mode is optimized to look for consecutive pixels in either the hilite or
  52523. background colors. For example, if the source is an all black pattern, the highlighting
  52524. will be especially fast, operating internally on a long word at a time instead of a
  52525. pixel at a time. Highlighting a large area without such consecutive pixels (a gray
  52526. pattern, for instance) can be slow.
  52527.  
  52528. The global variable HiliteRGB is read from parameter RAM when the machine starts. Old
  52529. grafPorts use the RGB values in the global HiliteRGB as the highlight color. Color
  52530. grafPorts default to the global HiliteRGB, but can be overridden by the HiliteColor
  52531. procedure.
  52532.  
  52533. The constants used with hilite mode are listed below:
  52534.  
  52535. CONST
  52536.   hilite      = 50;
  52537.   pHiliteBit  = 0;    {this is the correct value for use when calling }
  52538.                       { the BitClear trap. BClr must use the assembly }
  52539.                       { language equate hiliteBit}
  52540.  
  52541. æKY pHiliteBit
  52542. æFc Quickdraw.h
  52543. æT #define
  52544. æD #define pHiliteBit 0 /*flag bit in HiliteMode used with BitClr procedure*/
  52545. æC 
  52546.  
  52547. æKY defQDColors
  52548. æFc Quickdraw.h
  52549. æT #define
  52550. æD #define defQDColors 127 /*resource ID of clut for default QDColors*/
  52551. æC 
  52552.  
  52553. æKY GrafVerb
  52554. frame
  52555. paint
  52556. erase
  52557. invert
  52558. fill
  52559. æFc Quickdraw.h
  52560. æT enum
  52561. æD enum {frame,paint,erase,invert,fill};
  52562. typedef unsigned char GrafVerb;
  52563. æC 
  52564.  
  52565. æKY PixelType
  52566. chunky
  52567. chunkyPlanar
  52568. planar
  52569. æFc Quickdraw.h
  52570. æT enum
  52571. æD enum {chunky,chunkyPlanar,planar};
  52572. typedef unsigned char PixelType;
  52573. æC 
  52574.  
  52575. æKY Bits16[16]
  52576. æFc Quickdraw.h
  52577. æT typedef
  52578. æD typedef short Bits16[16];
  52579. æC 
  52580.  
  52581. æKY Pattern[8]
  52582. æFc Quickdraw.h
  52583. æT typedef
  52584. æD typedef unsigned char Pattern[8];
  52585. typedef Pattern *PatPtr, **PatHandle;
  52586. æC 
  52587.  
  52588. æKY QDByte
  52589. æFc Quickdraw.h
  52590. æT typedef
  52591. æD typedef char QDByte, *QDPtr, **QDHandle;
  52592. æC 
  52593.  
  52594. æKY QDErr
  52595. æFc Quickdraw.h
  52596. æT typedef
  52597. æD typedef short QDErr;
  52598. æC 
  52599.  
  52600. æKY FontInfo
  52601. æFc Quickdraw.h
  52602. æT struct
  52603. æD struct FontInfo {
  52604.     short ascent;
  52605.     short descent;
  52606.     short widMax;
  52607.     short leading;
  52608. };
  52609.  
  52610. typedef struct FontInfo FontInfo;
  52611. æC 
  52612. GetFontInfo returns the following information about the current grafPort’s character
  52613. font, taking into consideration the style and size in which the characters will be
  52614. drawn:  the ascent, descent, maximum character width (the greatest distance the pen
  52615. will move when a character is drawn), and leading
  52616. (the vertical distance between the descent line and the ascent line below it), all in
  52617. pixels. The FontInfo data type is defined as follows:
  52618.  
  52619. TYPE  FontInfo  =  RECORD
  52620.                      ascent:   INTEGER;    {ascent}
  52621.                      descent:  INTEGER;    {descent}
  52622.                      widMax:   INTEGER;    {maximum character width}
  52623.                      leading:  INTEGER     {leading}
  52624.                    END;
  52625.  
  52626. The line height (in pixels) can be determined by adding the ascent, descent, and
  52627. leading.
  52628.  
  52629. æKY BitMap
  52630. BitMapPtr
  52631. BitMapHandle
  52632. æFc Quickdraw.h
  52633. æT struct
  52634. æD struct BitMap {
  52635.     Ptr baseAddr;
  52636.     short rowBytes;
  52637.     Rect bounds;
  52638. };
  52639.  
  52640. typedef struct BitMap BitMap;
  52641. typedef BitMap *BitMapPtr, **BitMapHandle;
  52642.  
  52643. æC 
  52644. _______________________________________________________________________________
  52645.  
  52646. »Bit Maps
  52647.  
  52648. A bit map in QuickDraw is a data structure that defines a physical bit image in terms
  52649. of the coordinate plane. A bit map has three parts:  a pointer to a bit image, the
  52650. row width of that image, and a boundary rectangle that gives the bit map both its
  52651. dimensions and a coordinate system.
  52652.  
  52653. There can be several bit maps pointing to the same bit image, each imposing a different
  52654. coordinate system on it. This important feature is explained in
  52655. “Coordinates in GrafPorts”, below.
  52656.  
  52657. As shown in Figure 7, the structure of a bit map is as follows:
  52658.  
  52659. TYPE BitMap =  RECORD
  52660.                  baseAddr:  Ptr;      {pointer to bit image}
  52661.                  rowBytes:  INTEGER;  {row width}
  52662.                  bounds:    Rect      {boundary rectangle}
  52663.                END;
  52664.  
  52665. •••Refer to Figure 7.•••
  52666.  
  52667. Figure 7–A Bit Map
  52668.  
  52669. BaseAddr is a pointer to the beginning of the bit image in memory. RowBytes is the
  52670. row width in bytes. Both of these must always be even:  A bit map must always begin
  52671. on a word boundary and contain an integral number of words in each row.
  52672.  
  52673. The bounds field is the bit map’s boundary rectangle, which both encloses the active
  52674. area of the bit image and imposes a coordinate system on it. The top left corner of
  52675. the boundary rectangle is aligned around the first bit in the bit image.
  52676.  
  52677. The relationship between the boundary rectangle and the bit image in a bit map is
  52678. simple yet very important. First, some general rules:
  52679.  
  52680.   •  Bits in a bit image fall between points on the coordinate plane.
  52681.   •  A rectangle that is H points wide and V points tall encloses
  52682.      exactly (H–1)*(V–1) bits.
  52683.  
  52684. The coordinate system assigns integer values to the lines that border and separate
  52685. bits, not to the bit positions themselves. For example, if a bit map is assigned the
  52686. boundary rectangle with corners (10,–8) and (34,8), the bottom right bit in the image
  52687. will be between horizontal coordinates 33 and 34, and between vertical coordinates 7
  52688. and 8 (see Figure 8).
  52689.  
  52690. •••Refer to Figure 8.•••
  52691.  
  52692. Figure 8–Coordinates and Bit Maps
  52693.  
  52694. The width of the boundary rectangle determines how many bits of one row are logically
  52695. owned by the bit map. This width must not exceed the number of bits in each row of
  52696. the bit image. The height of the boundary rectangle determines how many rows of the
  52697. image are logically owned by the bit map. The number of rows enclosed by the boundary
  52698. rectangle must not exceed the number of rows in the bit image.
  52699.  
  52700. Normally, the boundary rectangle completely encloses the bit image. If the rectangle
  52701. is smaller than the dimensions of the image, the least significant bits in each row,
  52702. as well as the last rows in the image, aren’t affected by any operations on the bit
  52703. map.
  52704.  
  52705. There’s a QuickDraw global variable, named screenBits, that contains a bit map corresponding
  52706. to the screen of the Macintosh being used. Wherever your program needs the exact
  52707. dimensions of the screen, it should get them from the boundary rectangle of this
  52708. variable.
  52709.  
  52710. æKY Cursor
  52711. CursPtr
  52712. CursHandle
  52713. æFc Quickdraw.h
  52714. æT struct
  52715. æD struct Cursor {
  52716.     Bits16 data;
  52717.     Bits16 mask;
  52718.     Point hotSpot;
  52719. };
  52720.  
  52721. typedef struct Cursor Cursor;
  52722. typedef Cursor *CursPtr, **CursHandle;
  52723.  
  52724. æC 
  52725.  
  52726. æKY PenState
  52727. æFc Quickdraw.h
  52728. æT struct
  52729. æD struct PenState {
  52730.     Point pnLoc;
  52731.     Point pnSize;
  52732.     short pnMode;
  52733.     Pattern pnPat;
  52734. };
  52735.  
  52736. typedef struct PenState PenState;
  52737. æC 
  52738. GetPenState saves the pen location, size, pattern, and mode in pnState, to be restored
  52739. later with SetPenState. This is useful when calling subroutines that operate in the
  52740. current port but must change the graphics pen:  Each such procedure can save the
  52741. pen’s state when it’s called, do whatever it needs to do, and restore the previous
  52742. pen state immediately before returning. The PenState data type is defined as follows:
  52743.  
  52744. TYPE  PenState  =  RECORD
  52745.                      pnLoc:   Point;    {pen location}
  52746.                      pnSize:  Point;    {pen size}
  52747.                      pnMode:  INTEGER;  {pen's transfer mode}
  52748.                      pnPat:   Pattern   {pen pattern}
  52749.                    END;
  52750.  
  52751. æKY Region
  52752. RgnPtr
  52753. RgnHandle
  52754. æFc Quickdraw.h
  52755. æT struct
  52756. æD struct Region {
  52757.     short rgnSize; /*size in bytes*/
  52758.     Rect rgnBBox; /*enclosing rectangle*/
  52759. };
  52760.  
  52761. typedef struct Region Region;
  52762. typedef Region *RgnPtr, **RgnHandle;
  52763.  
  52764. æC 
  52765. _______________________________________________________________________________
  52766.  
  52767. »Regions
  52768.  
  52769. Unlike most graphics packages that can manipulate only simple geometric structures
  52770. (usually rectilinear, at that), QuickDraw has the ability to gather an arbitrary set
  52771. of spatially coherent points into a structure called a region, and perform complex
  52772. yet rapid manipulations and calculations on such structures. Regions not only make
  52773. your programs simpler and faster, but will let you perform operations that would
  52774. otherwise be nearly impossible.
  52775.  
  52776. You define a region by calling routines that draw lines and shapes (even other regions).
  52777. The outline of a region should be one or more closed loops. A region can be concave
  52778. or convex, can consist of one area or many disjoint areas, and can even have “holes”
  52779. in the middle. In Figure 5, the region on the left has a hole in the middle, and the
  52780. region on the right consists of two disjoint areas.
  52781.  
  52782. •••Refer to Figure 5.•••
  52783.  
  52784. Figure 5–Regions
  52785.  
  52786. The data structure for a region consists of two fixed-length fields followed by a
  52787. variable-length field:
  52788.  
  52789. TYPE Region =  RECORD
  52790.                  rgnSize:  INTEGER;  {size in bytes}
  52791.                  rgnBBox:  Rect;     {enclosing rectangle}
  52792.                  {more data if not rectangular}
  52793.                END;
  52794.  
  52795. The rgnSize field contains the size, in bytes, of the region variable. The maximum
  52796. size of a region is 32K bytes. The rgnBBox field is a rectangle that completely
  52797. encloses the region.
  52798.  
  52799. The simplest region is a rectangle. In this case, the rgnBBox field defines the
  52800. entire region, and there’s no optional region data. For rectangular regions (or empty
  52801. regions), the rgnSize field contains 10.
  52802.  
  52803. The region definition data for nonrectangular regions is stored in a compact way that
  52804. allows for highly efficient access by QuickDraw routines.
  52805.  
  52806. All regions are accessed through handles:
  52807.  
  52808. TYPE  RgnPtr     = ^Region;
  52809.       RgnHandle  = ^RgnPtr;
  52810.  
  52811. Many calculations can be performed on regions. A region can be “expanded” or
  52812. “shrunk” and, given any two regions, QuickDraw can find their union, intersection,
  52813. difference, and exclusive-OR; it can also determine whether a given point intersects
  52814. a region, and so on.
  52815.  
  52816. æKY Picture
  52817. PicPtr
  52818. PicHandle
  52819. æFc Quickdraw.h
  52820. æT struct
  52821. æD struct Picture {
  52822.     short picSize;
  52823.     Rect picFrame;
  52824. };
  52825.  
  52826. typedef struct Picture Picture;
  52827. typedef Picture *PicPtr, **PicHandle;
  52828.  
  52829. æC 
  52830. _______________________________________________________________________________
  52831.  
  52832. »»Pictures
  52833.  
  52834. A picture in QuickDraw is a transcript of calls to routines that draw something—anything—in
  52835. a bit image. Pictures make it easy for one program to draw something defined in
  52836. another program, with great flexibility and without knowing the details about what’s
  52837. being drawn.
  52838.  
  52839. For each picture you define, you specify a rectangle that surrounds it; this rectangle
  52840. is called the picture frame. When you later call the procedure that plays back the
  52841. saved picture, you supply a destination rectangle, and QuickDraw scales the picture
  52842. so that its frame is completely aligned with the destination rectangle. Thus, the
  52843. picture may be expanded or shrunk to fit its destination rectangle. For example, if
  52844. the picture is a circle inside a square picture frame, and the destination rectangle
  52845. is not square, the picture will be drawn as an oval.
  52846.  
  52847. Since a picture may include any sequence of drawing commands, its data structure is a
  52848. variable-length entity. It consists of two fixed-length fields followed by a variable-length
  52849. field:
  52850.  
  52851. TYPE  Picture =  RECORD
  52852.                    picSize:   INTEGER;  {size in bytes}
  52853.                    picFrame:  Rect;     {picture frame}
  52854.                    {picture definition data}
  52855.                  END;
  52856.  
  52857. The picSize field contains the size, in bytes, of the picture variable. The picFrame
  52858. field is the picture frame that surrounds the picture and gives a frame of reference
  52859. for scaling when the picture is played back. The rest of the structure contains a
  52860. compact representation of the drawing commands that define the picture.
  52861.  
  52862. All pictures are accessed through handles:
  52863.  
  52864. TYPE  PicPtr      = ^Picture;
  52865.       PicHandle   = ^PicPtr;
  52866.  
  52867. To define a picture, you call a QuickDraw function that returns a picHandle, and then
  52868. call the drawing routines that define the picture.
  52869.  
  52870. QuickDraw also allows you to intersperse picture comments with the definition of a
  52871. picture. These comments, which do not affect the picture’s appearance, may be used to
  52872. provide additional information about the picture when it’s played back. This is
  52873. especially valuable when pictures are transmitted from one application to another.
  52874. There are two standard types of comments which, like parentheses, serve to group
  52875. drawing commands together (such as all the commands that draw a particular part of a
  52876. picture):
  52877.  
  52878. CONST  picLParen  =  0;
  52879.        picRParen  =  1;
  52880.  
  52881. The application defining the picture can use these standard comments as well as
  52882. comments of its own design.
  52883.  
  52884. •••Refer to Technical Notes #21, #91, & #154:•••
  52885. _______________________________________________________________________________
  52886.  
  52887. »Picture Record Structure
  52888.  
  52889. The Pascal record structure of version 1 and version 2 pictures is exactly the same.
  52890. In both, the picture begins with a picSize, then a picFrame (rect), followed by the
  52891. picture definition data. Since a picture may include any sequence of drawing commands,
  52892. its data structure is a variable-length entity. It consists of two fixed-length
  52893. fields followed by a variable-length field:
  52894.  
  52895. TYPE Picture = RECORD
  52896.                  picSize:     INTEGER;     {low order 16 bits of picture }
  52897.                                            { size}
  52898.                  picFrame:    Rect;        {picture frame, used as }
  52899.                                            { reference for scaling when }
  52900.                                            { the picture is drawn }
  52901.                  {picture definition data}
  52902.                END;
  52903.  
  52904. To maintain compatibility with the original picture format, the picSize field has not
  52905. been changed in version 2 pictures. However, the information in this field is only
  52906. useful if your application supports version 1 pictures not exceeding 32K bytes in
  52907. size. Because pictures can be much larger than the 32K limit imposed by the 2-byte
  52908. picSize field, use the GetHandleSize call to determine picture size if the picture is
  52909. in memory or the file size returned in pBFGetInfo if the picture resides in a file.
  52910.  
  52911. The picFrame field is the picture frame that surrounds the picture and gives a frame
  52912. of reference for scaling when the picture is played back. The rest of the structure
  52913. contains a compact representation of the image defined by the opcodes. The picture
  52914. definition data consists of a sequence of the opcodes listed in Table 3 in the Pict
  52915. Opcodes section, each followed by zero or more bytes of data. Every opcode has an
  52916. implicit or explicit size associated with it that indicates the number of data bytes
  52917. following that opcode, ranging from 2 to
  52918. 2^32 bytes (this maximum number of bytes applies to version 2 pictures only).
  52919.  
  52920. æKY Polygon
  52921. PolyPtr
  52922. PolyHandle
  52923. æFc Quickdraw.h
  52924. æT struct
  52925. æD struct Polygon {
  52926.     short polySize;
  52927.     Rect polyBBox;
  52928.     Point polyPoints[1];
  52929. };
  52930.  
  52931. typedef struct Polygon Polygon;
  52932. typedef Polygon *PolyPtr, **PolyHandle;
  52933.  
  52934. æC 
  52935. _______________________________________________________________________________
  52936.  
  52937. »Polygons
  52938.  
  52939. Polygons are similar to pictures in that you define them by a sequence of calls to
  52940. QuickDraw routines. They’re also similar to other shapes that QuickDraw knows about,
  52941. since there’s a set of procedures for performing graphic operations and calculations
  52942. on them.
  52943.  
  52944. A polygon is simply any sequence of connected lines (see Figure 18). You define a
  52945. polygon by moving to the starting point of the polygon and drawing lines from there
  52946. to the next point, from that point to the next, and so on.
  52947.  
  52948. The data structure for a polygon consists of two fixed-length fields followed by a
  52949. variable-length array:
  52950.  
  52951. TYPE  Polygon  =  RECORD
  52952.                     polySize:    INTEGER;  {size in bytes}
  52953.                     polyBBox:    Rect;     {enclosing rectangle}
  52954.                     polyPoints:  ARRAY[0..0] OF Point
  52955.                   END;
  52956.  
  52957. •••Refer to Figure 18.•••
  52958.  
  52959. Figure 18–Polygons
  52960.  
  52961. The polySize field contains the size, in bytes, of the polygon variable. The maximum
  52962. size of a polygon is 32K bytes. The polyBBox field is a rectangle that just encloses
  52963. the entire polygon. The polyPoints array expands as necessary to contain the points
  52964. of the polygon—the starting point followed by each successive point to which a line
  52965. is drawn.
  52966.  
  52967. Like pictures and regions, polygons are accessed through handles:
  52968.  
  52969. TYPE  PolyPtr     =  ^Polygon;
  52970.       PolyHandle  =  ^PolyPtr;
  52971.  
  52972. To define a polygon, you call a routine that returns a polyHandle, and then call the
  52973. line-drawing routines that define the polygon.
  52974.  
  52975. Just as for other shapes that QuickDraw knows about, there’s a set of graphic operations
  52976. to draw polygons on the screen. QuickDraw draws a polygon by moving to the starting
  52977. point and then drawing lines to the remaining points in succession, just as when the
  52978. routines were called to define the polygon. In this sense it “plays back” those
  52979. routine calls. As a result, polygons are not treated exactly the same as other QuickDraw
  52980. shapes. For example, the procedure that frames a polygon draws outside the actual
  52981. boundary of the polygon, because QuickDraw line-drawing routines draw below and to
  52982. the right of the pen location. The procedures that fill a polygon with a pattern,
  52983. however, stay within the boundary of the polygon; if the polygon’s ending point isn’t
  52984. the same as its starting point, these procedures add a line between them to complete
  52985. the shape.
  52986.  
  52987. QuickDraw also scales a polygon differently from a similarly-shaped region if it’s
  52988. being drawn as part of a picture:  When stretched, a slanted line is drawn more
  52989. smoothly if it’s part of a polygon rather than a region. You may find it helpful to
  52990. keep in mind the conceptual difference between polygons and regions:  A polygon is
  52991. treated more as a continuous shape, a region more as a set of bits.
  52992.  
  52993. æKY QDProcs
  52994. QDProcsPtr
  52995. æFc Quickdraw.h
  52996. æT struct
  52997. æD struct QDProcs {
  52998.     Ptr textProc;
  52999.     Ptr lineProc;
  53000.     Ptr rectProc;
  53001.     Ptr rRectProc;
  53002.     Ptr ovalProc;
  53003.     Ptr arcProc;
  53004.     Ptr polyProc;
  53005.     Ptr rgnProc;
  53006.     Ptr bitsProc;
  53007.     Ptr commentProc;
  53008.     Ptr txMeasProc;
  53009.     Ptr getPicProc;
  53010.     Ptr putPicProc;
  53011. };
  53012.  
  53013. typedef struct QDProcs QDProcs;
  53014. typedef QDProcs *QDProcsPtr;
  53015.  
  53016. æC 
  53017.  
  53018. æKY GrafPort
  53019. GrafPtr
  53020. æFc Quickdraw.h
  53021. æT struct
  53022. æD struct GrafPort {
  53023.     short device;
  53024.     BitMap portBits;
  53025.     Rect portRect;
  53026.     RgnHandle visRgn;
  53027.     RgnHandle clipRgn;
  53028.     Pattern bkPat;
  53029.     Pattern fillPat;
  53030.     Point pnLoc;
  53031.     Point pnSize;
  53032.     short pnMode;
  53033.     Pattern pnPat;
  53034.     short pnVis;
  53035.     short txFont;
  53036.     Style txFace; /*txFace is unpacked byte but push as short*/
  53037.     char filler;
  53038.     short txMode;
  53039.     short txSize;
  53040.     Fixed spExtra;
  53041.     long fgColor;
  53042.     long bkColor;
  53043.     short colrBit;
  53044.     short patStretch;
  53045.     Handle picSave;
  53046.     Handle rgnSave;
  53047.     Handle polySave;
  53048.     QDProcsPtr grafProcs;
  53049. };
  53050.  
  53051. typedef struct GrafPort GrafPort;
  53052. typedef GrafPort *GrafPtr;
  53053.  
  53054. typedef GrafPtr WindowPtr;
  53055.  
  53056. æC _______________________________________________________________________________
  53057.  
  53058. »THE DRAWING ENVIRONMENT:  GRAFPORT
  53059. _______________________________________________________________________________
  53060.  
  53061. A grafPort is a complete drawing environment that defines where and how graphic
  53062. operations will take place. You can have many grafPorts open at once, and each one
  53063. will have its own coordinate system, drawing pattern, background pattern, pen size
  53064. and location, character font and style, and bit map in which drawing takes place. You
  53065. can instantly switch from one port to another. GrafPorts are the structures upon
  53066. which a program builds windows, which are fundamental to the Macintosh “overlapping
  53067. windows” user interface. Besides being used for windows on the screen, grafPorts are
  53068. used for printing and for off-screen drawing.
  53069.  
  53070. A grafPort is defined as follows:
  53071.  
  53072. TYPE  GrafPtr   =  ^GrafPort;
  53073.       GrafPort  =  RECORD
  53074.                      device:      INTEGER;    {device-specific information}
  53075.                      portBits:    BitMap;     {grafPort's bit map}
  53076.                      portRect:    Rect;       {grafPort's rectangle}
  53077.                      visRgn:      RgnHandle;  {visible region}
  53078.                      clipRgn:     RgnHandle;  {clipping region}
  53079.                      bkPat:       Pattern;    {background pattern}
  53080.                      fillPat:     Pattern;    {fill pattern}
  53081.                      pnLoc:       Point;      {pen location}
  53082.                      pnSize:      Point;      {pen size}
  53083.                      pnMode:      INTEGER;    {pen's transfer mode}
  53084.                      pnPat:       Pattern;    {pen pattern}
  53085.                      pnVis:       INTEGER;    {pen visibility}
  53086.                      txFont:      INTEGER;    {font number for text}
  53087.                      txFace:      Style;      {text's character style}
  53088.                      txMode:      INTEGER;    {text's transfer mode}
  53089.                      txSize:      INTEGER;    {font size for text}
  53090.                      spExtra:     Fixed;      {extra space}
  53091.                      fgColor:     LONGINT;    {foreground color}
  53092.                      bkColor:     LONGINT;    {background color}
  53093.                      colrBit:     INTEGER;    {color bit}
  53094.                      patStretch:  INTEGER;    {used internally}
  53095.                      picSave:     Handle;     {picture being saved}
  53096.                      rgnSave:     Handle;     {region being saved}
  53097.                      polySave:    Handle;     {polygon being saved}
  53098.                      grafProcs:   QDProcsPtr  {low-level drawing routines}
  53099.                    END;
  53100.  
  53101. Note that picSave is a Handle used internally by QuickDraw while it is saving a
  53102. picture, and rgnSave and polySave are used by QuickDraw as flags; they are set to “1”
  53103. when the corresponding action is taking place.
  53104.  
  53105. All QuickDraw operations refer to grafPorts via grafPtrs. (For historical reasons,
  53106. grafPort is one of the few objects in the Macintosh system software that’s referred
  53107. to by a pointer rather than a handle.)
  53108.  
  53109. Warning:  You can access all fields and subfields of a grafPort normally,
  53110.           but you should not store new values directly into them. QuickDraw
  53111.           has routines for altering all fields of a grafPort, and using
  53112.           these routines ensures that changing a grafPort produces no
  53113.           unusual side effects.
  53114.  
  53115. The device field of a grafPort contains device-specific information that’s used by
  53116. the Font Manager to achieve the best possible results when drawing text in the grafPort.
  53117. There may be physical differences in the same logical font for different output
  53118. devices, to ensure the highest-quality printing on the device being used. The default
  53119. value of the device field is 0, for best results on output to the screen. For more
  53120. information, see the Font Manager chapter.
  53121.  
  53122. The portBits field is the bit map that points to the bit image to be used by the
  53123. grafPort. The default bit map uses the entire screen as its bit image. The bit map
  53124. may be changed to indicate a different structure in memory:  All graphics routines
  53125. work in exactly the same way regardless of whether their effects are visible on the
  53126. screen. A program can, for example, prepare an image to be printed on a printer
  53127. without ever displaying the image on the screen, or develop a picture in an off-screen
  53128. bit map before transferring it to the screen. The portBits.bounds rectangle determines
  53129. the coordinate system of the grafPort; all other coordinates in the grafPort are
  53130. expressed in this system.
  53131.  
  53132. The portRect field is a rectangle that defines a subset of the bit map that will be
  53133. used for drawing:  All drawing done by the application occurs inside the portRect.
  53134. Its coordinates are in the coordinate system defined by the portBits.bounds rectangle.
  53135. The portRect usually falls within the portBits.bounds rectangle, but it’s not required
  53136. to do so. The portRect usually defines the “writable” interior area of a window,
  53137. document, or other object on the screen.
  53138.  
  53139. The visRgn field is manipulated by the Window Manager; you will normally never change
  53140. a grafPort’s visRgn. It indicates the region of the grafPort that’s actually visible
  53141. on the screen, that is, the part of the window that’s not covered by other windows.
  53142. For example, if you move one window in front of another, the Window Manager logically
  53143. removes the area of overlap from the visRgn of the window in back. When you draw into
  53144. the back window, whatever’s being drawn is clipped to the visRgn so that it doesn’t
  53145. run over onto the front window. The default visRgn is set to the portRect.
  53146.  
  53147. The clipRgn is the grafPort’s clipping region, an arbitrary region that you can use
  53148. to limit drawing to any region within the portRect. If, for example, you want to draw
  53149. a half circle on the screen, you can set the clipRgn to half the square that would
  53150. enclose the whole circle, and then draw the whole circle. Only the half within the
  53151. clipRgn will actually be drawn in the grafPort. The default clipRgn is set arbitrarily
  53152. large, you have full control over its setting; as a matter of recommended programming
  53153. practice, it is advisable to make the default clipRgn rectangle smaller.
  53154.  
  53155. Figure 10 illustrates a typical bit map (as defined by portBits), portRect, visRgn,
  53156. and clipRgn.
  53157.  
  53158. •••Refer to Figure 10.•••
  53159.  
  53160. Figure 10–GrafPort Regions
  53161.  
  53162. The bkPat and fillPat fields of a grafPort contain patterns used by certain QuickDraw
  53163. routines. BkPat is the “background” pattern that’s used when an area is erased or
  53164. when bits are scrolled out of it. When asked to fill an area with a specified pattern,
  53165. QuickDraw stores the given pattern in the fillPat field and then calls a low-level
  53166. drawing routine that gets the pattern from that field. The various graphic operations
  53167. are discussed in detail later in the descriptions of individual QuickDraw routines.
  53168.  
  53169. Of the next ten fields, the first five determine characteristics of the graphics pen
  53170. and the last five determine characteristics of any text that may be drawn; these are
  53171. described in separate sections below.
  53172.  
  53173. The fgColor, bkColor, and colrBit fields contain values related to drawing in color.
  53174. FgColor is the grafPort’s foreground color and bkColor is its background color.
  53175. ColrBit tells the color imaging software which plane of the color picture to draw
  53176. into. For more information, see “Drawing in Color” in the section “General Discussion
  53177. of Drawing”.
  53178.  
  53179. The patStretch field is used during output to a printer to expand patterns if necessary.
  53180. The application should not change its value.
  53181.  
  53182. The picSave, rgnSave, and polySave fields reflect the state of picture, region, and
  53183. polygon definition, respectively. The application shouldn’t be concerned about exactly
  53184. what information the handle, if any, leads to; you may, however, save the current
  53185. value of rgnSave, set the field to NIL to disable the region definition, and later
  53186. restore it to the saved value to resume the region definition. The picSave and polySave
  53187. fields work similarly for pictures and polygons.
  53188.  
  53189. Finally, the grafProcs field may point to a special data structure that the application
  53190. stores into if it wants to customize QuickDraw drawing routines or use QuickDraw in
  53191. other advanced, highly specialized ways (see “Customizing QuickDraw Operations”). If
  53192. grafProcs is NIL, QuickDraw responds in the standard ways described in this chapter.
  53193.  
  53194. _______________________________________________________________________________
  53195.  
  53196. »Pen Characteristics
  53197.  
  53198. The pnLoc, pnSize, pnMode, pnPat, and pnVis fields of a grafPort deal with the graphics
  53199. “pen”. Each grafPort has one and only one such pen, which is used for drawing lines,
  53200. shapes, and text. The pen has four characteristics:  a location, a size (height and
  53201. width), a drawing mode, and a drawing pattern (see Figure
  53202. 11).
  53203.  
  53204. •••Refer to Figure 11.•••
  53205.  
  53206. Figure 11–A Graphics Pen
  53207.  
  53208. The pnLoc field specifies the point where QuickDraw will begin drawing the next line,
  53209. shape, or character. It can be anywhere on the coordinate plane:  There are no restrictions
  53210. on the movement or placement of the pen. Remember that the pen location is a point in
  53211. the grafPort’s coordinate system, not a pixel in a bit image. The top left corner of
  53212. the pen is at the pen location; the pen hangs below and to the right of this point.
  53213.  
  53214. The pen is rectangular in shape, and its width and height are specified by pnSize.
  53215. The default size is a 1-by-1-bit square; the width and height can range from (0,0) to
  53216. (30000,30000). If either the pen width or the pen height is less than 1, the pen will
  53217. not draw.
  53218.  
  53219. The pnMode and pnPat fields of a grafPort determine how the bits under the pen are
  53220. affected when lines or shapes are drawn. The pnPat is a pattern that’s used like the
  53221. “ink” in the pen. This pattern, like all other patterns drawn in the grafPort, is
  53222. always aligned with the port’s coordinate system:  The top left corner of the pattern
  53223. is aligned with the top left corner of the portRect, so that adjacent areas of the
  53224. same pattern will blend into a continuous, coordinated pattern.
  53225.  
  53226. The pnMode field determines how the pen pattern is to affect what’s already in the
  53227. bit image when lines or shapes are drawn. When the pen draws, QuickDraw first determines
  53228. what bits in the bit image will be affected and finds their corresponding bits in the
  53229. pattern. It then does a bit-by-bit comparison based on the pen mode, which specifies
  53230. one of eight Boolean operations to perform. The resulting bit is stored into its
  53231. proper place in the bit image. The pen modes are described under “Transfer Modes” in
  53232. the section “General Discussion of Drawing”.
  53233.  
  53234. The pnVis field determines the pen’s visibility, that is, whether it draws on the
  53235. screen. For more information, see the descriptions of HidePen and ShowPen under “Pen
  53236. and Line-Drawing Routines” in the “QuickDraw Routines” section.
  53237.  
  53238. _______________________________________________________________________________
  53239.  
  53240. »Text Characteristics
  53241.  
  53242. The txFont, txFace, txMode, txSize, and spExtra fields of a grafPort determine how
  53243. text will be drawn—the font, style, and size of characters and how they will be
  53244. placed in the bit image. QuickDraw can draw characters as quickly and easily as it
  53245. draws lines and shapes, and in many prepared fonts. Font means the complete set of
  53246. characters of one typeface. The characters may be drawn in any size and character
  53247. style (that is, with stylistic variations such as bold, italic, and underline).
  53248. Figure 12 shows two characters drawn by QuickDraw and some terms associated with
  53249. drawing text.
  53250.  
  53251. •••Refer to Figure 12.•••
  53252.  
  53253. Figure 12–QuickDraw Characters
  53254.  
  53255. Text is drawn with the base line positioned at the pen location.
  53256.  
  53257. The txFont field is a font number that identifies the character font to be used in
  53258. the grafPort. The font number 0 represents the system font. For more information
  53259. about the system font, the other font numbers recognized by the Font Manager, and the
  53260. construction, layout, and loading of fonts, see the Font Manager chapter.
  53261.  
  53262. A character font is defined as a collection of images that make up the individual
  53263. characters of the font. The characters can be of unequal widths, and they’re not
  53264. restricted to their “cells”:  The lower curl of a lowercase j, for example, can
  53265. stretch back under the previous character (typographers call this kerning). A font
  53266. can consist of up to 255 distinct characters, yet not all characters need to be
  53267. defined in a single font. In addition, each font contains a missing symbol to be
  53268. drawn in case of a request to draw a character that’s missing from the font.
  53269.  
  53270. The txFace field controls the character style of the text with values from the set
  53271. defined by the Style data type:
  53272.  
  53273. TYPE  StyleItem  = (bold,italic,underline,outline,shadow,condense,extend);
  53274.       Style      = SET OF StyleItem;
  53275.  
  53276. Assembly-language note:  In assembly language, this set is stored as a word
  53277.                          whose low-order byte contains bits representing the
  53278.                          style. The bit numbers are specified by the following
  53279.                          global constants:
  53280.  
  53281.                            boldBit       .EQU    0
  53282.                            italicBit     .EQU    1
  53283.                            ulineBit      .EQU    2
  53284.                            outlineBit    .EQU    3
  53285.                            shadowBit     .EQU    5
  53286.                            extendBit     .EQU    6
  53287.  
  53288.                          If all bits are 0, it represents the plain character
  53289.                          style.
  53290.  
  53291. You can apply stylistic variations either alone or in combination; Figure 13 illustrates
  53292. some as applied to the Geneva font. Most combinations usually look good only for
  53293. large font sizes.
  53294.  
  53295. •••Refer to Figure 13.•••
  53296.  
  53297. Figure 13–Stylistic Variations
  53298.  
  53299. If you specify bold, each character is repeatedly drawn one bit to the right an
  53300. appropriate number of times for extra thickness.
  53301.  
  53302. Italic adds an italic slant to the characters. Character bits above the base line are
  53303. skewed right; bits below the base line are skewed left.
  53304.  
  53305. Underline draws a line below the base line of the characters. If part of a character
  53306. descends below the base line (as “y” in Figure 13), the underline
  53307. isn’t drawn through the pixel on either side of the descending part.
  53308.  
  53309. Outline makes a hollow, outlined character rather than a solid one. Shadow also makes
  53310. an outlined character, but the outline is thickened below and to the right of the
  53311. character to achieve the effect of a shadow. If you specify bold along with outline
  53312. or shadow, the hollow part of the character is widened.
  53313.  
  53314. Condense and extend affect the horizontal distance between all characters, including
  53315. spaces. Condense decreases the distance between characters and extend increases it,
  53316. by an amount that the Font Manager determines is appropriate.
  53317.  
  53318. The txMode field controls the way characters are placed in the bit image. It functions
  53319. much like a pnMode:  When a character is drawn, QuickDraw determines which bits in
  53320. the bit image will be affected, does a bit-by-bit comparison based on the mode, and
  53321. stores the resulting bits into the bit image. These modes are described under “Transfer
  53322. Modes” in the section “General Discussion of Drawing”. Only three of them—srcOr,
  53323. srcXor, and srcBic—should be used for drawing text.
  53324.  
  53325. Note:  If you use scrCopy, some extra blank space will be appended at the
  53326.        end of the text.
  53327.  
  53328. The txSize field specifies the font size in points (where “point” is a typographical
  53329. term meaning approximately 1/72 inch). Any size from 1 to 127 points may be specified.
  53330. If the Font Manager doesn’t have the font in a specified size, it will scale a size
  53331. it does have as necessary to produce the size desired. A value of 0 in this field
  53332. represents the system font size (12 points).
  53333.  
  53334. Finally, the spExtra field is useful when a line of characters is to be drawn justified
  53335. such that it’s aligned with both a left and a right margin (sometimes called “full
  53336. justification”). SpExtra contains a fixed-point number equal to the average number of
  53337. pixels by which each space character should be widened to fill out the line. The
  53338. Fixed data type is described in the Macintosh Memory Management:  An Introduction
  53339. chapter.
  53340.  
  53341. _______________________________________________________________________________
  53342.  
  53343. »COORDINATES IN GRAFPORTS
  53344. _______________________________________________________________________________
  53345.  
  53346. Each grafPort has its own local coordinate system. All fields in the grafPort are
  53347. expressed in these coordinates, and all calculations and actions performed in QuickDraw
  53348. use the local coordinate system of the currently selected port.
  53349.  
  53350. Two things are important to remember:
  53351.  
  53352.   •  Each grafPort maps a portion of the coordinate plane into a similarly-
  53353.      sized portion of a bit image.
  53354.   •  The portBits.bounds rectangle defines the local coordinates for a grafPort.
  53355.  
  53356. The top left corner of portBits.bounds is always aligned around the first bit in the
  53357. bit image; the coordinates of that corner “anchor” a point on the grid to that bit in
  53358. the bit image. This forms a common reference point for multiple grafPorts that use
  53359. the same bit image (such as the screen); given a portBits.bounds rectangle for each
  53360. port, you know that their top left corners coincide.
  53361.  
  53362. The relationship between the portBits.bounds and portRect rectangles is very important:
  53363.  The portBits.bounds rectangle establishes a coordinate system for the port, and the
  53364. portRect rectangle indicates the section of the coordinate plane (and thus the bit
  53365. image) that will be used for drawing. The portRect usually falls inside the portBits.bounds
  53366. rectangle, but it’s not required to do so.
  53367.  
  53368. When a new grafPort is created, its bit map is set to point to the entire screen, and
  53369. both the portBits.bounds and the portRect are set to rectangles enclosing the screen.
  53370. The point (0,0) corresponds to the screen’s top left corner.
  53371.  
  53372. You can redefine the local coordinates of the top left corner of the grafPort’s
  53373. portRect, using the SetOrigin procedure. This offsets the coordinates of the grafPort’s
  53374. portBits.bounds rectangle, recalculating the coordinates of all points in the grafPort
  53375. to be relative to the new corner coordinates. For example, consider these procedure
  53376. calls:
  53377.  
  53378.   SetPort(gamePort);
  53379.   SetOrigin(90,80)
  53380.  
  53381. The call to SetPort sets the current grafPort to gamePort; the call to SetOrigin
  53382. changes the local coordinates of the top left corner of that port’s portRect to
  53383. (90,80) (see Figure 14).
  53384.  
  53385. •••Refer to Figure 14.•••
  53386.  
  53387. Figure 14–Changing Local Coordinates
  53388.  
  53389. This offsets the coordinates of the following elements:
  53390.  
  53391.   gamePort^.portBits.bounds
  53392.   gamePort^.portRect
  53393.   gamePort^.visRgn
  53394.  
  53395. These three elements are always kept “in sync”.
  53396.  
  53397. Notice that when the local coordinates of a grafPort are offset, the grafPort’s
  53398. clipRgn and pen location are not offset. A good way to think of it is that the port’s
  53399. structure “sticks” to the screen, while the document in the grafPort
  53400. (along with the pen and clipRgn) “sticks” to the coordinate system. For example, in
  53401. Figure 14, before SetOrigin, the visRgn and clipRgn are the same as the portRect.
  53402. After the SetOrigin call, the locations of portBits.bounds, portRect, and visRgn do
  53403. not change on the screen; their coordinates are simply offset. As always, the top
  53404. left corner of portBits.bounds remains “anchored” around the first bit in the bit
  53405. image (the first pixel on the screen); the image on the screen doesn’t move as a
  53406. result of SetOrigin. However, the pen location and clipRgn do move on the screen; the
  53407. top left corner of the clipRgn is still
  53408. (100,100), but this location has moved down and to the right, and the pen has similarly
  53409. moved.
  53410.  
  53411. If you’re moving, comparing, or otherwise dealing with mathematical items in different
  53412. grafPorts (for example, finding the intersection of two regions in two different
  53413. grafPorts), you must adjust to a common coordinate system before you perform the
  53414. operation. A QuickDraw procedure, LocalToGlobal, lets you convert a point’s local
  53415. coordinates to a global coordinate system where the top left corner of the bit image
  53416. is (0,0); by converting the various local coordinates to global coordinates, you can
  53417. compare and mix them with confidence. For more information, see the description of
  53418. LocaltoGlobal under “Calculations with Points” in the “QuickDraw Routines” section.
  53419.  
  53420. æKY RGBColor
  53421. æFc Quickdraw.h
  53422. æT struct
  53423. æD struct RGBColor {
  53424.     unsigned short red; /*magnitude of red component*/
  53425.     unsigned short green; /*magnitude of green component*/
  53426.     unsigned short blue; /*magnitude of blue component*/
  53427. };
  53428.  
  53429. typedef struct RGBColor RGBColor;
  53430. typedef pascal Boolean (*ColorSearchProcPtr)(RGBColor *rgb, long *position);
  53431. typedef pascal Boolean (*ColorComplementProcPtr)(RGBColor *rgb);
  53432.  
  53433.  
  53434. æC 
  53435. _______________________________________________________________________________
  53436.  
  53437. »Drawing Color in a CGrafPort
  53438.  
  53439. Color QuickDraw represents color using the RGBColor record type, which specifies the
  53440. red, blue, and green components of the color. Three 16-bit unsigned integers give the
  53441. intensity values for the three additive primary colors:
  53442.  
  53443. TYPE
  53444.     RGBColor = RECORD
  53445.                  red:     INTEGER;    {red component}
  53446.                  green:   INTEGER;    {green component}
  53447.                  blue:    INTEGER     {blue component}
  53448.                END;
  53449.  
  53450. A color of this form is referred to as an RGB value and is the form in which an
  53451. application specifies the colors it needs. The translation from the RGB value to the
  53452. pixel value is performed at the time the color is drawn.  At times the pixel value is
  53453. stored in the fgColor or bkColor fields. Refer to the Graphics Devices chapter for
  53454. more details.
  53455.  
  53456. When drawing is actually performed, QuickDraw calls the Color Manager to supply the
  53457. color that most closely matches the requested color for the current device. As described
  53458. in the Color Manager chapter, you can replace the method used for color matching if
  53459. necessary. Normally pixel values are handled entirely by Color QuickDraw and the
  53460. Color Manager; applications only refer to colors as RGB values.
  53461.  
  53462. A set of colors is grouped into a structure called a color table:
  53463.  
  53464. TYPE
  53465.   CTabHandle = ^CTabPtr;
  53466.   CTabPtr    = ^ColorTable;
  53467.   ColorTable = RECORD
  53468.                  ctSeed:    LONGINT;     {unique identifier from table}
  53469.                  ctFlags:    INTEGER;    {contains flags describing the }
  53470.                                          { specArray; clear for a pixMap}
  53471.                  ctSize:     INTEGER;    {number of entries -1 }
  53472.                                          { in ctTable}
  53473.                  ctTable:    cSpecArray
  53474.                END;
  53475.  
  53476. The fields of a color table are fully described in the Color Manager chapter. The
  53477. ctFlags field contains flags that differentiate between a device color table and an
  53478. image color table. The ctTable field is composed of a cSpecArray, which contains an
  53479. array of ColorSpec entries. Notice that each entry in the color table is a ColorSpec,
  53480. not simply an RGBColor. The type ColorSpec is composed of a value field and an RGB
  53481. value, as shown below.
  53482.  
  53483. TYPE
  53484.   cSpecArray : ARRAY [0..0] of ColorSpec;
  53485.   ColorSpec = RECORD
  53486.                 value:    INTEGER;    {pixel value}
  53487.                 rgb:      RGBColor    {RGB value}
  53488.               END;
  53489.  
  53490. Color tables are used to represent the set of colors that a device is capable of
  53491. displaying, and they are used to describe the desired colors in an image. If the
  53492. color table describes an image’s colors, then a ColorSpec determines the desired RGB
  53493. for the pixel value stored in the value field. This is the most common usage, and
  53494. most of the routines described in this chapter work with a ColorSpec in this manner.
  53495.  
  53496. If the color table describes a device’s colors, then the value field in a ColorSpec
  53497. is reserved for use by the Color Manager. In most cases your application won’t change
  53498. the device color table. If you want to know more about the device color table, refer
  53499. to the Color Manager chapter for more details.
  53500.  
  53501. æKY ColorSpec
  53502. æFc Quickdraw.h
  53503. æT struct
  53504. æD struct ColorSpec {
  53505.     short value; /*index or other value*/
  53506.     RGBColor rgb; /*true color*/
  53507. };
  53508.  
  53509. typedef struct ColorSpec ColorSpec;
  53510. typedef ColorSpec CSpecArray[1]; /* array [0..0] of ColorSpec */
  53511.  
  53512. æC 
  53513. The fields of a color table are fully described in the Color Manager chapter. The
  53514. ctFlags field contains flags that differentiate between a device color table and an
  53515. image color table. The ctTable field is composed of a cSpecArray, which contains an
  53516. array of ColorSpec entries. Notice that each entry in the color table is a ColorSpec,
  53517. not simply an RGBColor. The type ColorSpec is composed of a value field and an RGB
  53518. value, as shown below.
  53519.  
  53520. TYPE
  53521.   cSpecArray : ARRAY [0..0] of ColorSpec;
  53522.   ColorSpec = RECORD
  53523.                 value:    INTEGER;    {pixel value}
  53524.                 rgb:      RGBColor    {RGB value}
  53525.               END;
  53526.  
  53527. Color tables are used to represent the set of colors that a device is capable of
  53528. displaying, and they are used to describe the desired colors in an image. If the
  53529. color table describes an image’s colors, then a ColorSpec determines the desired RGB
  53530. for the pixel value stored in the value field. This is the most common usage, and
  53531. most of the routines described in this chapter work with a ColorSpec in this manner.
  53532.  
  53533. If the color table describes a device’s colors, then the value field in a ColorSpec
  53534. is reserved for use by the Color Manager. In most cases your application won’t change
  53535. the device color table. If you want to know more about the device color table, refer
  53536. to the Color Manager chapter for more details.
  53537.  
  53538. æKY ColorTable
  53539. CTabPtr
  53540. CTabHandle
  53541. æFc Quickdraw.h
  53542. æT struct
  53543. æD struct ColorTable {
  53544.     long ctSeed; /*unique identifier for table*/
  53545.     short ctFlags; /*high bit: 0 = PixMap; 1 = device*/
  53546.     short ctSize; /*number of entries in CTTable*/
  53547.     CSpecArray ctTable; /*array [0..0] of ColorSpec*/
  53548. };
  53549.  
  53550. typedef struct ColorTable ColorTable;
  53551. typedef ColorTable *CTabPtr, **CTabHandle;
  53552.  
  53553. æC 
  53554. _______________________________________________________________________________
  53555.  
  53556. »Color Table Format
  53557.  
  53558. The complete set of colors in use at a given time for a particular gDevice is summarized
  53559. in a color table record. Its format is as follows:
  53560.  
  53561. TYPE
  53562.   CTabHandle = ^CTabPtr;
  53563.   CTabPtr    = ^ColorTable;
  53564.   ColorTable = RECORD
  53565.                  ctSeed:   LONGINT;  {unique identifier from table}
  53566.                  ctFlags:  INTEGER;  {high bit is set for a gDevice, }
  53567.                                      { clear for a pixMap}
  53568.                  ctSize:   INTEGER;  {Number of entries in table-1}
  53569.                  ctTable:    cSpecArray
  53570.                END;
  53571.  
  53572. Field descriptions
  53573.  
  53574. ctSeed     The ctSeed field is similar to a version identifier number for
  53575.            a color table. If a color table is created by an application, it
  53576.            should call GetCTSeed to obtain this identifier. The ctSeed should
  53577.            be some unique number higher than minSeed, a predefined constant
  53578.            with a value of 1023. If a color table is created from a resource,
  53579.            its resource number will be used as the initial ctSeed. For 'CLUT'
  53580.            resource, the range of resource numbers should be 0–1023.
  53581.  
  53582. ctFlags    The ctFlags field is significant for gDevices only. It contains
  53583.            flags that describe the format of the ctTable. Currently, only
  53584.            the high bit is defined; all others are reserved. Color tables
  53585.            that are part of the gDevice structure always have this bit set.
  53586.            Color tables that are part of pixMaps have this bit clear. Each
  53587.            gDevice has its own pixMap, which has a color table.
  53588.  
  53589. ctSize     The ctSize field contains the number of entries in the color
  53590.            table minus one. All counts on color table entries are zero based.
  53591.  
  53592. ctTable    The ctTable field contains a cSpecArray, which is an array of
  53593.            ColorSpec entries. Notice that each entry in the color table is
  53594.            a ColorSpec, not simply an RGBColor. The type ColorSpec is
  53595.            composed of an integer value and an RGB color, as shown in the
  53596.            following specification. A color table may include a number of
  53597.            ColorSpec records.
  53598.  
  53599. TYPE
  53600.   cSpecArray = ARRAY [0..0] OF ColorSpec;
  53601.   ColorSpec  = RECORD
  53602.                  value : INTEGER;    {Color representation}
  53603.                  rgb   : RGBColor    {Color value}
  53604.                END;
  53605.   RGBColor   = RECORD
  53606.                  red   : INTEGER;    {Red component}
  53607.                  green : INTEGER;    {Green component}
  53608.                  blue  : INTEGER     {Blue component}
  53609.                END;
  53610.  
  53611. In gDevice color tables, the colorSpec.value field is reserved for use by the Color
  53612. Manager and Palette Manager. Their interpretation and values are different than the
  53613. color tables contained in pixMaps.
  53614.  
  53615. •••Refer to Figure 1.•••
  53616.  
  53617. Figure 1–Color Table Format
  53618.  
  53619. Note that the colorSpec.value field of the record is only word size (16 bits), even
  53620. though color index values (as returned by Color2Index) may be long words. The current
  53621. implementation of Color QuickDraw only supports 16 bits. The components in an RGBColor
  53622. are left-justified rather than right-justified in a word. Video drivers should respect
  53623. this convention and extract the appropriate number of bits from the high order side
  53624. of the component. For example, the Apple Graphics Card uses only the most significant
  53625. eight bits of each component of the RGBColor record.
  53626.  
  53627. æKY MatchRec
  53628. æFc Quickdraw.h
  53629. æT struct
  53630. æD struct MatchRec {
  53631.     unsigned short red;
  53632.     unsigned short green;
  53633.     unsigned short blue;
  53634.     long matchData;
  53635. };
  53636.  
  53637. typedef struct MatchRec MatchRec;
  53638. æC 
  53639. The SeedCFill procedure generates a mask for use with CopyMask or CopyBits, with bits
  53640. equal to 1 only in those positions where paint can leak from the starting seed point,
  53641. like the MacPaint® bucket tool.
  53642.  
  53643. Given a rectangle within a source bitMap or pixMap (srcBits), SeedCFill returns a
  53644. mask (dstBits) that contains 1’s in place of all pixels to which paint can leak from
  53645. the specified seed position (seedH, seedV), expressed in the local coordinate system
  53646. of the source pixMap. By default, paint can leak to all adjacent pixels whose RGB
  53647. value exactly match that of the seed. To use this default, set matchProc and matchData
  53648. to zero.
  53649.  
  53650. In generating the mask, SeedCFill performs CopyBits to convert srcBits to a
  53651. one-bit mask. It installs a default searchProc into the gDevice that returns 0 if the
  53652. RGB value matches that of the seed; all other RGB values return 1’s.
  53653.  
  53654. If you want to customize SeedCFill, your application can specify a matchProc that is
  53655. used instead of the default searchProc. It should return 0’s for RGB values that you
  53656. want to be filled, and 1’s for values that shouldn’t be filled. When the matchProc is
  53657. called, the GDRefCon field of the current gDevice contains a pointer to a record
  53658. having the following structure:
  53659.  
  53660. MatchRec = RECORD
  53661.              red:          INTEGER;
  53662.              green:        INTEGER;
  53663.              blue:         INTEGER;
  53664.              matchData:    LONGINT
  53665.            END;
  53666.  
  53667. In this record the red, green, and blue fields are the RGB of the pixel at the specified
  53668. seed location. MatchData is simply whatever value you passed to SeedCFill as a parameter.
  53669. For instance, your application could pass a handle to a color table whose entries
  53670. should all be filled, and then, in the matchProc, check to see if the specified RGB
  53671. matches any of the colors in the table.
  53672.  
  53673. No automatic scaling is performed: the source and destination rectangles must be the
  53674. same size. Calls to SeedCFill are not clipped to the current port and are not stored
  53675. into QuickDraw pictures.
  53676.  
  53677. æKY PixMap
  53678. PixMapPtr
  53679. PixMapHandle
  53680. æFc Quickdraw.h
  53681. æT struct
  53682. æD struct PixMap {
  53683.     Ptr baseAddr; /*pointer to pixels*/
  53684.     short rowBytes; /*offset to next line*/
  53685.     Rect bounds; /*encloses bitmap*/
  53686.     short pmVersion; /*pixMap version number*/
  53687.     short packType; /*defines packing format*/
  53688.     long packSize; /*length of pixel data*/
  53689.     Fixed hRes; /*horiz. resolution (ppi)*/
  53690.     Fixed vRes; /*vert. resolution (ppi)*/
  53691.     short pixelType; /*defines pixel type*/
  53692.     short pixelSize; /*# bits in pixel*/
  53693.     short cmpCount; /*# components in pixel*/
  53694.     short cmpSize; /*# bits per component*/
  53695.     long planeBytes; /*offset to next plane*/
  53696.     CTabHandle pmTable; /*color map for this pixMap*/
  53697.     long pmReserved; /*for future use. MUST BE 0*/
  53698. };
  53699.  
  53700. typedef struct PixMap PixMap;
  53701. typedef PixMap *PixMapPtr, **PixMapHandle;
  53702.  
  53703. æC 
  53704. _______________________________________________________________________________
  53705.  
  53706. »Pixel Maps
  53707.  
  53708. Just as the original QuickDraw does all of its drawing in a bit map, Color QuickDraw
  53709. uses an extended data structure called a pixel map (pixMap). In addition to the
  53710. dimensions and contents of a pixel image, the pixel map also includes information on
  53711. the image’s storage format, depth, resolution, and color usage:
  53712.  
  53713. TYPE
  53714.  PixMapHandle = ^PixMapPtr;
  53715.  PixMapPtr    = ^PixMap;
  53716.  PixMap       = RECORD
  53717.                   baseAddr:      Ptr;           {pointer to pixMap data}
  53718.                   rowBytes:      INTEGER;       {offset to next row}
  53719.                   bounds:        Rect;          {boundary rectangle}
  53720.                   pmVersion:     INTEGER;       {color QuickDraw version }
  53721.                                                 { number}
  53722.                   packType:      INTEGER;       {packing format}
  53723.                   packSize:      LONGINT;       {size of data in packed }
  53724.                                                 { state}
  53725.                   hRes:          Fixed;         {horizontal resolution}
  53726.                   vRes:          Fixed;         {vertical resolution}
  53727.                   pixelType:     INTEGER;       {format of pixel image}
  53728.                   pixelSize:     INTEGER;       {physical bits per pixel}
  53729.                   cmpCount:      INTEGER;       {logical components per }
  53730.                                                 { pixel}
  53731.                   cmpSize:       INTEGER;       {logical bits per component}
  53732.                   planeBytes:    LONGINT;       {offset to next plane}
  53733.                   pmTable:       CTabHandle;    {absolute colors for this }
  53734.                                                 { image}
  53735.                   pmReserved:    LONGINT        {reserved for future }
  53736.                                                 { expansion}
  53737.                 END;
  53738.  
  53739. Field descriptions
  53740.  
  53741. baseAddr      The baseAddr field contains a pointer to first byte of the
  53742.               pixel image, the same as in a bitMap. For optimal performance
  53743.               this should be a multiple of four.
  53744.  
  53745. rowBytes      The rowBytes field contains the offset in bytes from one row of
  53746.               the image to the next, the same as in a bitMap. As before,
  53747.               rowBytes must be even. The high three bits of rowBytes are used
  53748.               as flags. If bit 15 = 1, the data structure is a pixMap;
  53749.               otherwise it is a bitMap. Bits 14 and 13 are not used and must
  53750.               be 0.
  53751.  
  53752. bounds        The bounds field is the boundary rectangle, which defines the
  53753.               coordinate system and extent of the pixel map; it’s similar to
  53754.               a bitMap. This rectangle is in pixels, so depth has no effect
  53755.               on its values.
  53756.  
  53757. pmVersion     The pmVersion is the version number of Color QuickDraw that
  53758.               created this pixel map, which is provided for future
  53759.               compatibility. (Initial release is version 0.)
  53760.  
  53761. packType      The packType field identifies the packing algorithm used to
  53762.               compress image data. Color QuickDraw currently supports only
  53763.               packType = 0, which means no packing.
  53764.  
  53765. packSize      The packSize field contains the size of the packed image in
  53766.               bytes. When packType = 0, this field should be set to 0.
  53767.  
  53768. hRes          The hRes is the horizontal resolution of pixMap data in pixels
  53769.               per inch.
  53770.  
  53771. vRes          The vRes is the vertical resolution of pixMap data in pixels
  53772.               per inch. By default, hRes = vRes = 72 pixels per inch.
  53773.  
  53774. pixelType     The pixelType field specifies the storage format for a pixel
  53775.               image. 0 = chunky, 1 = chunky/planar, 2 = planar. Only chunky
  53776.               is used in the Macintosh II.
  53777.  
  53778. pixelSize     The pixelSize is the physical bits per pixel; it’s always a
  53779.               power of 2.
  53780.  
  53781. cmpCount      The cmpCount is the number of color components per pixel. For
  53782.               chunky pixel images, this is always 1.
  53783.  
  53784. cmpSize       The cmpSize field contains the logical bits per RGBColor
  53785.               component. Note that (cmpCount*cmpSize) doesn’t necessarily
  53786.               equal pixelSize. For chunky pixel images, cmpSize = pixelSize.
  53787.  
  53788. planeBytes    The planeBytes field is the offset in bytes from one plane to
  53789.               the next. If only one plane is used, as is the case with chunky
  53790.               pixel images, this field is set to 0.
  53791.  
  53792. pmTable       The pmTable field is a handle to table of colors used in the
  53793.               pixMap. This may be a device color table or an image color table.
  53794.  
  53795. pmReserved    The pmReserved field is reserved for future expansion; it must
  53796.               be set to 0 for future compatibility.
  53797.  
  53798. The data in a pixel image can be organized several ways, depending on the characteristics
  53799. of the device or image. The pixMap data structure supports three pixel image formats:
  53800. chunky, planar, and chunky/planar.
  53801.  
  53802. In a chunky pixel image, all of a pixel’s bits are stored consecutively in memory,
  53803. all of a row’s pixels are stored consecutively, and rowBytes indicates the offset in
  53804. memory from one row to the next. This is the only one of the three formats that’s
  53805. supported by this implementation of Color QuickDraw. The pixel depths that are currently
  53806. supported are 1, 2, 4, and 8 bits per pixel. In a chunky pixMap cmpCount = 1 and
  53807. cmpSize = pixelSize. Figure 5 shows a chunky pixel image for a system with screen
  53808. depth set to eight.
  53809.  
  53810. A planar pixel image is a pixel image separated into distinct bit images in memory,
  53811. one for each color plane. Within the bit image, rowBytes indicates the offset in
  53812. memory from one row to the next. PlaneBytes indicates the offset in memory from one
  53813. plane to the next. The planar format isn’t supported by this implementation of Color
  53814. QuickDraw.
  53815.  
  53816. A chunky/planar pixel image is separated into distinct pixel images in memory, typically
  53817. one for each color component. Within the pixel image, rowBytes indicates the offset
  53818. in memory from one row to the next. PlaneBytes indicates the offset in memory from
  53819. one plane to the next. The chunky/planar format isn’t supported by this implementation
  53820. of Color QuickDraw.
  53821.  
  53822. •••Refer to Figure 5.•••
  53823.  
  53824. Figure 5–A Pixel Image
  53825.  
  53826. æKY PixPat
  53827. PixPatPtr
  53828. PixPatHandle
  53829. æFc Quickdraw.h
  53830. æT struct
  53831. æD struct PixPat {
  53832.     short patType; /*type of pattern*/
  53833.     PixMapHandle patMap; /*the pattern's pixMap*/
  53834.     Handle patData; /*pixmap's data*/
  53835.     Handle patXData; /*expanded Pattern data*/
  53836.     short patXValid; /*flags whether expanded Pattern valid*/
  53837.     Handle patXMap; /*Handle to expanded Pattern data*/
  53838.     Pattern pat1Data; /*old-Style pattern/RGB color*/
  53839. };
  53840.  
  53841. typedef struct PixPat PixPat;
  53842. typedef PixPat *PixPatPtr, **PixPatHandle;
  53843.  
  53844. æC 
  53845. _______________________________________________________________________________
  53846.  
  53847. »Pixel Patterns
  53848.  
  53849. With Color QuickDraw, monochrome patterns are replaced by a new form of pattern
  53850. structure, the pixel pattern, which offers greater flexibility in the use of color. 
  53851. The three pattern fields in a grafPort—pnPat, bkPat, and fillPat—have been replaced
  53852. by the pnPixPat, bkPixPat, and fillPixPat fields in a cGrafPort. The format for a
  53853. pixel pattern is shown below:
  53854.  
  53855. TYPE
  53856.   PixPatHandle = ^PixPatPtr;
  53857.   PixPatPtr    = ^PixPat;
  53858.   PixPat       = RECORD
  53859.                    patType:      INTEGER;         {pattern type}
  53860.                    patMap:       PixMapHandle;    {pattern characteristics}
  53861.                    patData:      Handle;          {pixel image defining }
  53862.                                                   { pattern}
  53863.                    patXData:     Handle;          {expanded pixel image}
  53864.                    patXValid:    INTEGER;         {flags for expanded }
  53865.                                                   { pattern data}
  53866.                    patXMap:      Handle;          {handle to expanded }
  53867.                                                   { pattern data}
  53868.                    pat1Data:      Pattern;        {old-style pattern/RGB }
  53869.                                                   { color}
  53870.                  END;
  53871.  
  53872. Field descriptions
  53873.  
  53874. patType      The patType field specifies the pattern’s type. The possible
  53875.              values include: 0 = old-style pattern, 1 = full-color pixel
  53876.              pattern, 2 = RGB pattern.
  53877.  
  53878. patMap       The patMap field is a handle to the pixel map describing the
  53879.              pattern’s pixel image.
  53880.  
  53881. patData      The patData field is a handle to the pattern’s pixel image.
  53882.  
  53883. patXData     The patXData field is a handle to an expanded pixel image used
  53884.              internally by Color QuickDraw.
  53885.  
  53886. patXValid    When the pattern’s data or color table change, you can
  53887.              invalidate the expanded data by setting the patXValid field to –1.
  53888.  
  53889. patXMap      The patXMap field is a handle that is reserved for use by Color
  53890.              QuickDraw.
  53891.  
  53892. pat1Data    The pat1Data field contains an old-style 8-by-8 pattern to be
  53893.             used when this pattern is drawn into old grafPort. NewPixPat
  53894.             sets this field to 50% gray.
  53895.  
  53896. Old-style patterns are still supported. When used in a cGrafPort, the QuickDraw
  53897. routines PenPat and BackPat store the pattern within pnPixPat and bkPixPat, respectively,
  53898. and set the patType to 0 to indicate that the structure contains old pattern data.
  53899. Such patterns are limited to the original 8-by-8 dimensions and are always drawn
  53900. using the values in the cGrafPort’s rgbFgColor and rgbBkColor fields. Similarly,
  53901. filled drawing operations, such as FillRect, are also supported.
  53902.  
  53903. In a pixel pattern (patType = 1), the pattern’s dimensions, depth, resolution
  53904. (only 72 pixels per inch is supported), set of colors, and other characteristics are
  53905. defined by a pixel map, referenced by the patMap handle. Since the pixel map has its
  53906. own color table, pixel patterns can consist of any number of colors, and don’t usually
  53907. use the foreground and background colors. The section on relative patterns, below,
  53908. describes an exception to this rule.
  53909.  
  53910. Furthermore, patType = 1 patterns are not limited to a fixed size: their height and
  53911. width can be any power of 2, as specified by the height and width of
  53912. patMap^^.bounds. (Notice that a pattern eight bits wide—the original QuickDraw size—has
  53913. a row width of just one byte, contrary to the usual rule that the rowBytes field must
  53914. be even.) This pattern type is generally read into memory using the GetPixPat routine,
  53915. or set using the PenPixPat or BackPixPat routines.
  53916.  
  53917. Although the patMap defines the pattern’s characteristics, its baseAddr field is
  53918. ignored; for a type1 pattern, the actual pixel image defining the pattern is stored
  53919. in the handle in the pattern’s patData field. The pattern’s depth need not match that
  53920. of the pixel map it’s painted into; the depth will be adjusted automatically when the
  53921. pattern is drawn. Color QuickDraw maintains a private copy of the pattern’s pixel
  53922. image, expanded to the current screen depth, and aligned to the current grafPort or
  53923. cGrafPort, in the patXData field.
  53924.  
  53925. The third pattern type is RGBPat (patType = 2). Using the MakeRGBPat routine, the
  53926. application can specify the exact color it wants to use. QuickDraw selects a pattern
  53927. to approximate that color. In this way, an application can effectively increase the
  53928. color resolution of the screen. Pixel patterns are particularly useful for dithering:
  53929. mixing existing colors together to create the illusion of a third color that’s unavailable
  53930. on a particular device. The MakeRGBPat routine aids in this process by constructing a
  53931. dithered pattern to approximate a given absolute color. (See the description of
  53932. MakeRGBPat in the
  53933. “Color QuickDraw Routines” section for more details.) In the current implementation
  53934. of Color QuickDraw, an RGBPat can display 125 different patterns on a 4-bit-deep
  53935. screen, or 2197 different patterns on an 8-bit-deep screen.
  53936.  
  53937. For an RGBPat, the RGB defines the image; there is no image data. An RGBPat has an
  53938. 8-by-8, 2-bit-deep pattern.
  53939.  
  53940. A program that creates a pixMap must initialize the pixMap’s color table to describe
  53941. the pixels. GetCTable could be used to read such a table from a resource file; you
  53942. could then dispose of the pixMap’s color table and replace it with the one returned
  53943. by GetCTable.
  53944.  
  53945. »Relative Patterns
  53946.  
  53947. Type1 pixel patterns contain color tables that describe the colors they use. Generally
  53948. such a color table contains one entry for each color used in the pattern. For instance,
  53949. if your pattern has five colors in it, you would probably create a four-bit-per-pixel
  53950. pattern that uses pixel values 0–4, and a color table with five entries, numbered
  53951. 0–4, that contain the RGB specifications for those pixel values.
  53952.  
  53953. When the pattern is drawn, each possible pixel value that isn’t specified in the
  53954. color table is assigned a color. The largest unassigned pixel value becomes the
  53955. foreground color; the smallest unassigned pixel value is assigned the background
  53956. color. Remaining unassigned pixel values are given colors that are evenly distributed
  53957. between the foreground and background.
  53958.  
  53959. For instance, in the color table mentioned above, pixel values 5–15 are unused.
  53960. Assume that the foreground color is black and the background color is white. Pixel
  53961. value 15 is assigned the foreground color, black; pixel value 5 is assigned the
  53962. background color, white; the nine pixel values between them are assigned evenly
  53963. distributed shades of gray. If the pixMap’s color table is set to NIL, all pixel
  53964. values are determined by blending the foreground and background colors.
  53965.  
  53966. æKY CCrsr
  53967. CCrsrPtr
  53968. CCrsrHandle
  53969. æFc Quickdraw.h
  53970. æT struct
  53971. æD struct CCrsr {
  53972.     short crsrType; /*type of cursor*/
  53973.     PixMapHandle crsrMap; /*the cursor's pixmap*/
  53974.     Handle crsrData; /*cursor's data*/
  53975.     Handle crsrXData; /*expanded cursor data*/
  53976.     short crsrXValid; /*depth of expanded data (0 if none)*/
  53977.     Handle crsrXHandle; /*future use*/
  53978.     Bits16 crsr1Data; /*one-bit cursor*/
  53979.     Bits16 crsrMask; /*cursor's mask*/
  53980.     Point crsrHotSpot; /*cursor's hotspot*/
  53981.     long crsrXTable; /*private*/
  53982.     long crsrID; /*private*/
  53983. };
  53984.  
  53985. typedef struct CCrsr CCrsr;
  53986. typedef CCrsr *CCrsrPtr, **CCrsrHandle;
  53987.  
  53988. æC 
  53989. _______________________________________________________________________________
  53990.  
  53991. »THE COLOR CURSOR
  53992. _______________________________________________________________________________
  53993.  
  53994. Color QuickDraw supports the use of color cursors. The size of a cursor is still
  53995. 16-by-16 pixels. The new CCrsr data structure is substantially different from the
  53996. Cursor data structure used with the original QuickDraw: the CCrsr fields crsr1Data,
  53997. crsrMask, and crsrHotSpot are the only fields that have counterparts in the Cursor
  53998. record.
  53999.  
  54000. The structure of the color cursor is as follows:
  54001.  
  54002. TYPE
  54003.    CCrsrHandle = ^CCrsrPtr;
  54004.    CCrsrPtr    = ^CCrsr;
  54005.    CCrsr       = RECORD
  54006.                    crsrType:       INTEGER;          {type of cursor}
  54007.                    crsrMap:        PixMapHandle;     {the cursor's pixmap}
  54008.                    crsrData:       Handle;           {cursor's data}
  54009.                    crsrXData:      Handle;           {expanded cursor data}
  54010.                    crsrXValid:     INTEGER;          {depth of expanded data}
  54011.                    crsrXHandle:    Handle;           {Reserved for future }
  54012.                                                      { use}
  54013.                    crsr1Data:      Bits16;           {one-bit cursor}
  54014.                    crsrMask:       Bits16;           {cursor's mask}
  54015.                    crsrHotSpot:    Point;            {cursor's hotspot}
  54016.                    crsrXTable:     LONGINT;          {private}
  54017.                    crsrID:         LONGINT;          {ctSeed for expanded }
  54018.                                                      { cursor}
  54019.                  END;
  54020.  
  54021. You will not normally need to manipulate the fields of a color cursor. Your application
  54022. can load in a color cursor using the GetCCursor routine, and display it using the
  54023. SetCCursor routine. When the application is finished using a color cursor, it should
  54024. dispose of it using the DisposCCursor routine. These routines are discussed below in
  54025. the section “Color QuickDraw Routines”.
  54026.  
  54027. Color cursors are stored in resources of type 'crsr'. The format of the 'crsr' resource
  54028. is given in the section “Color QuickDraw Resource Formats”.
  54029.  
  54030. Field descriptions
  54031.  
  54032. crsrType       The crsrType field specifies the type of cursor. Possible
  54033.                values are: $8000 = old cursor, $8001 = new cursor.
  54034.  
  54035. crsrMap        The crsrMap field is a handle to the pixel map defining the
  54036.                cursor’s characteristics.
  54037.  
  54038. crsrData       The crsrData field is a handle to the cursor’s pixel data.
  54039.  
  54040. crsrXData      The crsrXData field is a handle to the expanded pixel image
  54041.                used internally by Color QuickDraw (private).
  54042.  
  54043. crsrXValid     The crsrXValid field contains the depth of the expanded cursor
  54044.                image. If you change the cursor’s data or color table, you
  54045.                should set this field to 0 to cause the cursor to be reexpanded.
  54046.                You should never set it to any other values.
  54047.  
  54048. crsrXHandle    The crsrXHandle field is reserved for future use.
  54049.  
  54050. crsr1Data      The crsr1Data field contains a 16-by-16 one-bit image to be
  54051.                displayed when the cursor is on 1-bit or 2-bit per pixel screens.
  54052.  
  54053. crsrMask       The crsrMask field contains the cursor’s mask data. The same
  54054.                1-bit-deep mask is used with crsrData and crsr1Data.
  54055.  
  54056. crsrHotSpot    The crsrHotSpot field contains the cursor’s hot spot.
  54057.  
  54058. crsrXTable     The crsrXTable field is reserved for future use.
  54059.  
  54060. crsrID         The crsrID field contains the ctSeed for the cursor.
  54061.  
  54062. The first four fields of the CCrsr record are similar to the first four fields of the
  54063. PixPat record, and are used in the same manner by Color QuickDraw. See the discussion
  54064. of the patMap field under the section titled “Pixel Patterns” for more information on
  54065. how the crsrMap is used.
  54066.  
  54067. The display of a cursor involves a relationship between a mask, stored in the crsrMask
  54068. field with the same format used for old cursor masks, and an image. There are two
  54069. possible sources for a color cursor’s image. When the cursor is on a screen whose
  54070. depth is one or two bits per pixel, the image for the cursor is taken from Crsr1Data,
  54071. which contains old-style cursor data. In this case, the relationship between data and
  54072. mask is exactly as before.  When the screen depth is greater than two bits per pixel,
  54073. the image for the cursor is taken from crsrMap and crsrData; the relationship between
  54074. mask and data is described in the following paragraph.
  54075.  
  54076. The data pixels within the mask replace the destination pixels. The data pixels
  54077. outside the mask are displayed using an XOR with the destination pixels. If data
  54078. pixels outside the mask are 0 (white), the destination pixels aren’t changed. If data
  54079. pixels outside the mask are all 1’s (black), the destination pixels are complemented.
  54080. All other values outside of the mask cause unpredictable results.
  54081.  
  54082. To work properly, a color cursor’s image should contain white pixels
  54083. (R = G = B = $FFFF) for the transparent part of the image, and black pixels
  54084. (R = G = B = $0000) for the inverting part of the image, in addition to the other
  54085. colors in the cursor’s image. Thus, to define a cursor that contains two colors, it’s
  54086. necessary to use a 2-bit-per-pixel cursor image (that is, a four-color image).
  54087.  
  54088. If your application changes the value of your cursor data or its color table, it
  54089. should set the crsrXValid field to 0 to indicate that the cursor’s data needs to be
  54090. reexpanded, and assign a new unique value to crsrID (unique values can be obtained
  54091. using the GetCTSeed routine); then it should call SetCCursor to display the changed
  54092. cursor.
  54093.  
  54094. æKY CIcon
  54095. CIconPtr
  54096. CIconHandle
  54097. æFc Quickdraw.h
  54098. æT struct
  54099. æD struct CIcon {
  54100.     PixMap iconPMap; /*the icon's pixMap*/
  54101.     BitMap iconMask; /*the icon's mask*/
  54102.     BitMap iconBMap; /*the icon's bitMap*/
  54103.     Handle iconData; /*the icon's data*/
  54104.     short iconMaskData[1]; /*icon's mask and BitMap data*/
  54105. };
  54106.  
  54107. typedef struct CIcon CIcon;
  54108. typedef CIcon *CIconPtr, **CIconHandle;
  54109.  
  54110. æC 
  54111. _______________________________________________________________________________
  54112.  
  54113. »COLOR ICONS
  54114. _______________________________________________________________________________
  54115.  
  54116. A new data structure, known as CIcon, supports the use of color icons. The structure
  54117. of the color icon is as follows:
  54118.  
  54119. TYPE
  54120.    CIconHandle = ^CIconPtr;
  54121.    CIconPtr    = ^CIcon;
  54122.    CIcon       = RECORD
  54123.                    iconPMap:        PixMap;    {the icon's pixMap}
  54124.                    iconMask:        BitMap;    {the icon's mask bitmap}
  54125.                    iconBMap:        BitMap;    {the icon's bitMap}
  54126.                    iconData:        Handle;    {the icon's data}
  54127.                    iconMaskData:    ARRAY[0..0] OF INTEGER;
  54128.                                                {icon's mask and bitmap }
  54129.                                                { data}
  54130.                  END;
  54131.  
  54132. You won’t normally need to manipulate the fields of color icons. Your application can
  54133. load a color icon into memory using the routine GetCIcon. To draw a color icon that’s
  54134. already in memory, use PlotCIcon. When your application is through with a color icon,
  54135. it can dispose of it using the DisposCIcon routine. These routines are discussed
  54136. below in the section “Color QuickDraw Routines”.
  54137.  
  54138. Color icons are stored in a resource file as resource type 'cicn'. The format of the
  54139. 'cicn' resource is given in the section “Using Color QuickDraw
  54140. Resources”.
  54141.  
  54142. Field descriptions
  54143.  
  54144. iconPMap        The iconPMap field contains the pixel map describing the
  54145.                 icon. Note that pixMap is inline, not a handle.
  54146.  
  54147. iconMask        The iconMask field contains a bit map for the icon’s mask.
  54148.  
  54149. iconBMap        The iconBMap field contains a bit map for the icon.
  54150.  
  54151. iconData        The iconData field contains a handle to the icon’s pixel image.
  54152.  
  54153. iconMaskData    The iconMaskData field is an array containing the icon’s mask
  54154.                 data followed by the icon’s bitmap data. This is only used
  54155.                 when the icon is stored as a resource.
  54156.  
  54157. You can use color icons in menus in the same way that you could use old icons in
  54158. menus. The menu definition procedure first tries to load in a 'cicn' with the specified
  54159. resource ID. If it doesn’t find one, then it tries to load in an
  54160. 'ICON' with that ID. The Dialog Manager will also use a 'cicn' in place of an
  54161. 'ICON' if there is one with the ID specified in the item list. For more information,
  54162. see the Menu Manager and Dialog Manager chapters.
  54163.  
  54164. æKY GammaTbl
  54165. GammaTblPtr
  54166. GammaTblHandle
  54167. æFc Quickdraw.h
  54168. æT struct
  54169. æD struct GammaTbl {
  54170.     short gVersion; /*gamma version number*/
  54171.     short gType; /*gamma data type*/
  54172.     short gFormulaSize; /*Formula data size*/
  54173.     short gChanCnt; /*number of channels of data*/
  54174.     short gDataCnt; /*number of values/channel*/
  54175.     short gDataWidth; /*bits/corrected value (data packed to next larger byte size)*/
  54176.     short gFormulaData[1]; /*data for formulas followed by gamma values*/
  54177. };
  54178.  
  54179. typedef struct GammaTbl GammaTbl;
  54180. typedef GammaTbl *GammaTblPtr, **GammaTblHandle;
  54181.  
  54182. æC 
  54183.  
  54184. æKY ITab
  54185. ITabPtr
  54186. ITabHandle
  54187. æFc Quickdraw.h
  54188. æT struct
  54189. æD struct ITab {
  54190.     long iTabSeed; /*copy of CTSeed from source CTable*/
  54191.     short iTabRes; /*bits/channel resolution of iTable*/
  54192.     unsigned char iTTable[1]; /*byte colortable index values*/
  54193. };
  54194.  
  54195. typedef struct ITab ITab;
  54196. typedef ITab *ITabPtr, **ITabHandle;
  54197.  
  54198. æC 
  54199.  
  54200. æKY SProcRec
  54201. SProcPtr
  54202. SProcHndl
  54203. æFc Quickdraw.h
  54204. æT struct
  54205. æD struct SProcRec {
  54206.     Handle nxtSrch; /*SProcHndl Handle to next SProcRec*/
  54207.     ColorSearchProcPtr srchProc; /*pointer to search procedure*/
  54208. };
  54209.  
  54210. typedef struct SProcRec SProcRec;
  54211. typedef SProcRec *SProcPtr, **SProcHndl;
  54212.  
  54213. æC 
  54214.  
  54215. æKY CProcRec
  54216. CProcPtr
  54217. CProcHndl
  54218. æFc Quickdraw.h
  54219. æT struct
  54220. æD struct CProcRec {
  54221.     Handle nxtComp; /*CProcHndl Handle to next CProcRec*/
  54222.     ColorComplementProcPtr compProc; /*pointer to complement procedure*/
  54223. };
  54224.  
  54225. typedef struct CProcRec CProcRec;
  54226. typedef CProcRec *CProcPtr, **CProcHndl;
  54227.  
  54228. æC 
  54229.  
  54230. æKY GDevice
  54231. GDPtr
  54232. GDHandle
  54233. æFc Quickdraw.h
  54234. æT struct
  54235. æD struct GDevice {
  54236.     short gdRefNum; /*driver's unit number*/
  54237.     short gdID; /*client ID for search procs*/
  54238.     short gdType; /*fixed/CLUT/direct*/
  54239.     ITabHandle gdITable; /*Handle to inverse lookup table*/
  54240.     short gdResPref; /*preferred resolution of GDITable*/
  54241.     SProcHndl gdSearchProc; /*search proc list head*/
  54242.     CProcHndl gdCompProc; /*complement proc list*/
  54243.     short gdFlags; /*grafDevice flags word*/
  54244.     PixMapHandle gdPMap; /*describing pixMap*/
  54245.     long gdRefCon; /*reference value*/
  54246.     Handle gdNextGD; /*GDHandle Handle of next gDevice*/
  54247.     Rect gdRect; /* device's bounds in global coordinates*/
  54248.     long gdMode; /*device's current mode*/
  54249.     short gdCCBytes; /*depth of expanded cursor data*/
  54250.     short gdCCDepth; /*depth of expanded cursor data*/
  54251.     Handle gdCCXData; /*Handle to cursor's expanded data*/
  54252.     Handle gdCCXMask; /*Handle to cursor's expanded mask*/
  54253.     long gdReserved; /*future use. MUST BE 0*/
  54254. };
  54255.  
  54256. typedef struct GDevice GDevice;
  54257. typedef GDevice *GDPtr, **GDHandle;
  54258.  
  54259. æC 
  54260. _______________________________________________________________________________
  54261.  
  54262. »DEVICE RECORDS
  54263. _______________________________________________________________________________
  54264.  
  54265. All information that is needed to communicate with a graphics device is stored in a
  54266. handle to a gDevice record, called a gdHandle.  This information may describe many
  54267. types of devices, including video displays, printers, or offscreen drawing environments.
  54268.  
  54269. The structure of the gDevice record is as follows:
  54270.  
  54271. TYPE
  54272.    GDHandle = ^GDPtr;
  54273.    GDPtr    = ^GDevice;
  54274.    GDevice  = RECORD
  54275.                 gdRefNum:      INTEGER;       {reference number of driver}
  54276.                 gdID:          INTEGER;       {client ID for search procedure}
  54277.                 gdType:        INTEGER;       {device type}
  54278.                 gdITable:      ITabHandle;    {inverse table}
  54279.                 gdResPref:     INTEGER;       {preferred resolution}
  54280.                 gdSearchProc:  SProcHndl;     {list of search procedures}
  54281.                 gdCompProc:    CProcHndl;     {list of complement procedures}
  54282.                 gdFlags:       INTEGER;       {grafDevice flags word}
  54283.                 gdPMap:        PixMapHandle;  {pixel map for displayed image}
  54284.                 gdRefCon:      LONGINT;       {reference value}
  54285.                 gdnextGD:      GDHandle;      {handle of next gDevice}
  54286.                 gdRect:        Rect;          {device's global bounds}
  54287.                 gdMode:        LONGINT;       {device's current mode}
  54288.                 gdCCBytes:     INTEGER;       {rowBytes of expanded cursor data}
  54289.                 gdCCDepth:     INTEGER;       {rowBytes of expanded cursor data}
  54290.                 gdCCXData:     Handle;        {handle to cursor's expanded data}
  54291.                 gdCCXMask:     Handle;        {handle to cursor's expanded mask}
  54292.                 gdReserved:    LONGINT        {reserved for future expansion}
  54293.               END;
  54294.  
  54295. Field descriptions
  54296.  
  54297. gdRefNum        The gdRefNum is a reference number of the driver for the
  54298.                 display device associated with this card. For most display
  54299.                 devices, this information is set at system startup time.
  54300.  
  54301. gdID            The gdID field contains an application-settable ID number
  54302.                 identifying the current client of the port. It is also used
  54303.                 for search and complement procedures (see “The Color Manager:
  54304.                 Search and Complement Procedures”).
  54305.  
  54306. gdType          The gdType field specifies the general type of device.
  54307.                 Values include:
  54308.  
  54309.                   0 = CLUT device (mapped colors with lookup table)
  54310.                   1 = fixed colors (no lookup table)
  54311.                   2 = direct RGB
  54312.  
  54313.                 These device types are described in the Color Manager chapter.
  54314.  
  54315. gdITable        The gdITable contains a handle to the inverse table for
  54316.                 color mapping (see “The Color Manager: Inverse Tables”).
  54317.  
  54318. gdResPref       The gdResPref field contains the preferred resolution for
  54319.                 inverse tables (see “The Color Manager: Inverse Tables”).
  54320.  
  54321. gdSearchProc    The gdSearchProc field is a pointer to the list of search
  54322.                 procedures (see “The Color Manager: Search and Complement
  54323.                 Procedures”); its value is NIL for a default procedure.
  54324.  
  54325. gdCompProc      The gdCompProc field is a pointer to a list of complement
  54326.                 procedures (see “The Color Manager: Search and Complement
  54327.                 Procedures”; its value is NIL for a default procedure.
  54328.  
  54329. gdFlags         The gdFlags field contains the gDevice’s attributes. Do not
  54330.                 set these flags directly; always use the procedures described
  54331.                 in this chapter.
  54332.  
  54333. gdPMap          The gdPMap field is a handle to a pixel map giving
  54334.                 the dimension of the image buffer, along with the
  54335.                 characteristics of the device (resolution, storage format,
  54336.                 color depth, color table). For gDevices, the high bit of
  54337.                 theGDevice^^.gdPMap^^.pmTable^^.ctFlags is always set.
  54338.  
  54339. gdRefCon        The gdRefCon is a field used to pass device-related
  54340.                 parameters (see SeedCFill and CalcCMask in the Color
  54341.                 QuickDraw chapter). Since a device is shared, you shouldn’t
  54342.                 store data here.
  54343.  
  54344. gdNextGD        The gdNextGD field contains a handle to the next device in
  54345.                 the deviceList. If  this is the last device in the deviceList,
  54346.                 this is set to zero.
  54347.  
  54348. gdRect          The gdRect field contains the boundary rectangle of the
  54349.                 gDevice.  The screen with the menu bar has topLeft = 0,0.
  54350.                 All other devices are relative to it.
  54351.  
  54352. gdMode          The gdMode field specifies the current setting for the
  54353.                 device mode.  This is the value passed to the driver to
  54354.                 set its pixel depth, etc.
  54355.  
  54356. gdCCBytes       The gdCCBytes field contains the rowBytes of the expanded
  54357.                 cursor. Applications must not change this field.
  54358.  
  54359. gdCCDepth       The gdCCDepth field contains the depth of the expanded
  54360.                 cursor. Applications must not change this field.
  54361.  
  54362. gdCCXData       The gdCCXData field contains a handle to the cursor’s
  54363.                 expanded data. Applications must not change this field.
  54364.  
  54365. gdCCXMask       The gdCCXMask field contains a handle to the cursor’s
  54366.                 expanded mask. Applications must not change this field.
  54367.  
  54368. gdReserved      The gdReserved field is reserved for future expansion;
  54369.                 it must be set to zero for future compatibility.
  54370.  
  54371. æKY GrafVars
  54372. GVarPtr
  54373. GVarHandle
  54374. æFc Quickdraw.h
  54375. æT struct
  54376. æD struct GrafVars {
  54377.     RGBColor rgbOpColor; /*color for addPin  subPin and average*/
  54378.     RGBColor rgbHiliteColor; /*color for hiliting*/
  54379.     Handle pmFgColor; /*palette Handle for foreground color*/
  54380.     short pmFgIndex; /*index value for foreground*/
  54381.     Handle pmBkColor; /*palette Handle for background color*/
  54382.     short pmBkIndex; /*index value for background*/
  54383.     short pmFlags; /*flags for Palette Manager*/
  54384. };
  54385.  
  54386. typedef struct GrafVars GrafVars;
  54387. typedef GrafVars *GVarPtr, **GVarHandle;
  54388.  
  54389. æC 
  54390. The OpenCPort procedure is analogous to OpenPort, except it opens a cGrafPort instead
  54391. of a grafPort. You will rarely need to use this call, since OpenCPort is called by
  54392. NewCWindow and GetNewCWindow, as well as by the Dialog Manager when the appropriate
  54393. color resources are present.  OpenCPort allocates storage for all the structures in
  54394. the cGrafPort, and then calls InitCPort to initialize them.  The new structures
  54395. allocated are the portPixMap, the pnPixPat, the fillPixPat, the bkPixPat, and the
  54396. grafVars handle.  The GrafVars record structure is shown below:
  54397.  
  54398. TYPE
  54399. GrafVars = RECORD
  54400.              rgbOpColor:        RGBColor;    {color for addPin, subPin, and }
  54401.                                              { blend}
  54402.              rgbHiliteColor:    RGBColor;    {color for highlighting}
  54403.              pmFgColor:         Handle;      {Palette handle for foreground }
  54404.                                              { color}
  54405.              pmFgIndex:         INTEGER;     {index value for foreground}
  54406.              pmBkColor:         Handle;      {Palette handle for background }
  54407.                                              { color}
  54408.              pmBkIndex:         INTEGER;     {index value for background}
  54409.              pmFlags:           INTEGER;     {Flags for Palette Manager}
  54410.            END;
  54411.  
  54412. The rgbOpColor field is initialized as black, and the rgbHiliteColor field is initialized
  54413. as the default HiliteRGB. All the rest of the GrafVars fields are initially zero.
  54414.  
  54415. The portPixMap is not allocated a color table of its own. When InitCPort is called,
  54416. the handle to the current device’s color table is copied into the portPixMap.
  54417.  
  54418. æKY CQDProcs
  54419. CQDProcsPtr
  54420. æFc Quickdraw.h
  54421. æT struct
  54422. æD struct CQDProcs {
  54423.     Ptr textProc;
  54424.     Ptr lineProc;
  54425.     Ptr rectProc;
  54426.     Ptr rRectProc;
  54427.     Ptr ovalProc;
  54428.     Ptr arcProc;
  54429.     Ptr polyProc;
  54430.     Ptr rgnProc;
  54431.     Ptr bitsProc;
  54432.     Ptr commentProc;
  54433.     Ptr txMeasProc;
  54434.     Ptr getPicProc;
  54435.     Ptr putPicProc;
  54436.     Ptr opcodeProc; /*fields added to QDProcs*/
  54437.     Ptr newProc1;
  54438.     Ptr newProc2;
  54439.     Ptr newProc3;
  54440.     Ptr newProc4;
  54441.     Ptr newProc5;
  54442.     Ptr newProc6;
  54443. };
  54444.  
  54445. typedef struct CQDProcs CQDProcs;
  54446. typedef CQDProcs *CQDProcsPtr;
  54447.  
  54448. æC 
  54449. _______________________________________________________________________________
  54450.  
  54451. »New GrafProcs Record
  54452.  
  54453. The entire opcode space has been defined or reserved, as shown in the PICT Opcodes
  54454. section in Table 3, and a new set of routines has been added to the grafProcs record.
  54455. These changes provide support for anticipated future enhancements in a way that won’t
  54456. cause old applications to crash. It works like this: when Color QuickDraw encounters
  54457. an unused opcode, it calls the new opcodeProc routine to parse the opcode data.  By
  54458. default, this routine simply ignores the data, since no new opcodes are defined
  54459. (other than HeaderOp, which is also ignored).
  54460.  
  54461. Color QuickDraw has replaced the QDProcs record with a CQDProcs record.  In a new
  54462. grafPort, you should never use the SetStdProcs routine.  If you do, it will return
  54463. the old QDProcs record, which won’t contain an entry for the stdOpcodeProc.  If you
  54464. don’t use the new SetStdCProcs routine, the first color picture that you try to
  54465. display may crash your system.
  54466. The CQDProcs record structure is shown below. Only the last seven fields are new; the
  54467. rest of the fields are the same as those in the QDProcs record.
  54468.  
  54469.    CQDProcsPtr = ^CQDProcs
  54470.    CQDProcs    = RECORD
  54471.                    textProc:       Ptr;
  54472.                    lineProc:       Ptr;
  54473.                    rectProc:       Ptr;
  54474.                    rRectProc:      Ptr;
  54475.                    ovalProc:       Ptr;
  54476.                    arcProc:        Ptr;
  54477.                    polyProc:       Ptr;
  54478.                    rgnProc:        Ptr;
  54479.                    bitsProc:       Ptr;
  54480.                    commentProc:    Ptr;
  54481.                    txMeasProc:     Ptr;
  54482.                    getPicProc:     Ptr;
  54483.                    putPicProc:     Ptr;
  54484.                    opcodeProc:     Ptr;    {fields added to QDProcs}
  54485.                    newProc1:       Ptr;    {reserved for future use}
  54486.                    newProc2:       Ptr;    {reserved for future use}
  54487.                    newProc3:       Ptr;    {reserved for future use}
  54488.                    newProc4:       Ptr;    {reserved for future use}
  54489.                    newProc5:       Ptr;    {reserved for future use}
  54490.                    newProc6:       Ptr;    {reserved for future use}
  54491.                  END;
  54492.  
  54493. æKY CGrafPort
  54494. CGrafPtr
  54495. æFc Quickdraw.h
  54496. æT struct
  54497. æD struct CGrafPort {
  54498.     short device;
  54499.     PixMapHandle portPixMap; /*port's pixel map*/
  54500.     short portVersion; /*high 2 bits always set*/
  54501.     Handle grafVars; /*Handle to more fields*/
  54502.     short chExtra; /*character extra*/
  54503.     short pnLocHFrac; /*pen fraction*/
  54504.     Rect portRect;
  54505.     RgnHandle visRgn;
  54506.     RgnHandle clipRgn;
  54507.     PixPatHandle bkPixPat; /*background pattern*/
  54508.     RGBColor rgbFgColor; /*RGB components of fg*/
  54509.     RGBColor rgbBkColor; /*RGB components of bk*/
  54510.     Point pnLoc;
  54511.     Point pnSize;
  54512.     short pnMode;
  54513.     PixPatHandle pnPixPat;
  54514.     PixPatHandle fillPixPat;
  54515.     short pnVis;
  54516.     short txFont;
  54517.     Style txFace; /*txFace is unpacked byte  push as short*/
  54518.     char filler;
  54519.     short txMode;
  54520.     short txSize;
  54521.     Fixed spExtra;
  54522.     long fgColor;
  54523.     long bkColor;
  54524.     short colrBit;
  54525.     short patStretch;
  54526.     Handle picSave;
  54527.     Handle rgnSave;
  54528.     Handle polySave;
  54529.     CQDProcsPtr grafProcs;
  54530. };
  54531.  
  54532. typedef struct CGrafPort CGrafPort;
  54533. typedef CGrafPort *CGrafPtr;
  54534.  
  54535. typedef CGrafPtr CWindowPtr;
  54536.  
  54537. æC 
  54538. _______________________________________________________________________________
  54539.  
  54540. »THE COLOR GRAPHICS PORT
  54541. _______________________________________________________________________________
  54542.  
  54543. As described above, programs designed to take advantage of the more powerful new
  54544. color facilities available on the Macintosh II must use a new form of graphics port,
  54545. the color graphics port (type cGrafPort).  Color grafPorts will generally be created
  54546. indirectly, as a result of opening a color window with the new routines NewCWindow,
  54547. GetNewCWindow, and NewCDialog.
  54548.  
  54549. In addition, the old routines GetNewWindow, GetNewDialog, Alert, StopAlert, NoteAlert,
  54550. and CautionAlert will open a color grafPort if certain resources
  54551. (types 'wctb', 'dctb', or 'actb') are present. Refer to the chapters on the Window
  54552. and Dialog Managers for more details.
  54553.  
  54554. The new cGrafPort structure is the same size as the old-style grafPort and most of
  54555. its fields are unchanged. The old portBits field, which formerly held a complete
  54556. 14-byte BitMap record embedded within the grafPort, has been replaced by a 4-byte
  54557. PixMapHandle (portPixMap), freeing 10 bytes for other uses. (In particular, the new
  54558. portVersion field, in the position previously occupied by the bit map’s rowBytes
  54559. field, always has its two high
  54560.  
  54561. bits set; these bits are used to distinguish cGrafPorts from grafPorts, in which the
  54562. two high bits of rowBytes are always clear. See Figure 4.) Similarly, the old bkPat,
  54563. pnPat, and fillPat fields, which previously held 8-byte patterns, have been replaced
  54564. by three 4-byte handles. The resulting 12 bytes of additional space are taken up by
  54565. two 6-byte RGBColor records.
  54566.  
  54567. The structure of the color graphics port is as follows:
  54568.  
  54569.   CGrafPtr  = ^CGrafPort;
  54570.   CGrafPort = RECORD
  54571.                 device:         INTEGER;         {device ID for font }
  54572.                                                  { selection}
  54573.                 portPixMap:     PixMapHandle;    {port's pixel map}
  54574.                 portVersion:    INTEGER;         {highest 2 bits always }
  54575.                                                  { set}
  54576.                 grafVars:       Handle;          {handle to more fields}
  54577.                 chExtra:        INTEGER;         {extra characters}
  54578.                 pnLocHFrac:     INTEGER;         {pen fraction}
  54579.                 portRect:       Rect;            {port rectangle}
  54580.                 visRgn:         RgnHandle;       {visible region}
  54581.                 clipRgn:        RgnHandle;       {clipping region}
  54582.                 bkPixPat:       PixPatHandle;    {background pattern}
  54583.                 rgbFgColor:     RGBColor;        {requested foreground }
  54584.                                                  { color}
  54585.                 rgbBkColor:     RGBColor;        {requested background }
  54586.                                                  { color}
  54587.                 pnLoc:          Point;           {pen location}
  54588.                 pnSize:         Point;           {pen size}
  54589.                 pnMode:         INTEGER;         {pen transfer mode}
  54590.                 pnPixPat:       PixPatHandle;    {pen pattern}
  54591.                 fillPixPat:     PixPatHandle;    {fill pattern}
  54592.                 pnVis:          INTEGER;         {pen visibility}
  54593.                 txFont:         INTEGER;         {font number for text}
  54594.                 txFace:         Style;           {text's character style}
  54595.                 txMode:         INTEGER;         {text's transfer mode}
  54596.                 txSize:         INTEGER;         {font size for text}
  54597.                 spExtra:        Fixed;           {extra space}
  54598.                 fgColor:        LONGINT;         {actual foreground color}
  54599.                 bkColor:        LONGINT;         {actual background color}
  54600.                 colrBit:        INTEGER;         {plane being drawn}
  54601.                 patStretch:     INTEGER;         {used internally}
  54602.                 picSave:        Handle;          {picture being saved}
  54603.                 rgnSave:        Handle;          {region being saved}
  54604.                 polySave:       Handle;          {polygon being saved}
  54605.                 grafProcs:      CQDProcsPtr      {low-level drawing }
  54606.                                                  { routines}
  54607.               END;
  54608.  
  54609. Field descriptions
  54610.  
  54611. portPixMap     The portPixMap field contains a handle to the port’s pixel
  54612.                map. This is the structure that describes the cGrafPort’s pixels.
  54613.  
  54614. portVersion    The two high bits of the portVersion field are always set.
  54615.                This allows Color QuickDraw to tell the difference between a
  54616.                grafPort and a cGrafPort. The remainder of the field gives
  54617.                the version number of Color QuickDraw that created this port.
  54618.                (Initial release is version 0.)
  54619.  
  54620. grafVars       The grafVars field contains a handle to additional fields.
  54621.  
  54622. chExtra        The chExtra field is used in proportional spacing. It specifies
  54623.                a fixed point number by which to widen every character,
  54624.                excluding the space character, in a line of text. (The number
  54625.                is in 4.12 fractional notation: four bits of signed integer
  54626.                followed by 12 bits of fraction. This number is multiplied by
  54627.                txSize before it is used.) Default chExtra is 0.
  54628.  
  54629. pnLocHFrac     The pnLocHFrac field contains the fractional horizontal pen
  54630.                position used when drawing text. The initial pen fraction is 1/2.
  54631.  
  54632. bkPixPat       The bkPixPat field contains a handle to the background pixel
  54633.                pattern.
  54634.  
  54635. rgbFgColor     The rgbFgColor field contains the requested foreground color.
  54636.  
  54637. rgbBkColor     The rgbBkColor field contains the requested background color.
  54638.  
  54639. pnPixPat       The pnPixPat field contains a handle to the pixel pattern for
  54640.                pen drawing.
  54641.  
  54642. fillPixPat     The fillPixPat field contains a handle to the pixel pattern for
  54643.                area fill; for internal use only. Notice that this is not in
  54644.                the same location as old fillPat.
  54645.  
  54646. fgColor        The fgColor field contains the pixel value of the foreground
  54647.                color supplied by the Color Manager. This is the best available
  54648.                approximation to rgbFgColor.
  54649.  
  54650. bkColor        The bkColor field contains the pixel value of the background
  54651.                color supplied by the Color Manager. This is the best available
  54652.                approximation to rgbBkColor.
  54653.  
  54654. colrBit        The colrBit field is reserved: not for use by applications.
  54655.  
  54656. grafProc       The grafProc field used with a cGrafPort contains a CQDProcsPtr,
  54657.                instead of the QDProcsPtr used with a grafPort.
  54658.  
  54659. All remaining fields have the same meanings as in the old-style grafPort.
  54660.  
  54661. •••Refer to Figure 4.•••
  54662.  
  54663. Figure 4–Color QuickDraw Fields
  54664.  
  54665. æKY ReqListRec
  54666. æFc Quickdraw.h
  54667. æT struct
  54668. æD struct ReqListRec {
  54669.     short reqLSize; /*request list size*/
  54670.     short reqLData[1]; /*request list data*/
  54671. };
  54672.  
  54673. typedef struct ReqListRec ReqListRec;
  54674. æC 
  54675. SaveEntries saves a selection of entries from srcTable into resultTable. The entries
  54676. to be set are enumerated in the selection parameter, which uses the ReqListRec data
  54677. structure shown below. (These values are offsets into colorTable, not the contents of
  54678. the colorSpec.value field.)
  54679.  
  54680. TYPE
  54681.   ReqListRec = RECORD
  54682.                  reqLSize:  INTEGER;                 {request list size –1}
  54683.                  reqLData:  ARRAY [0..0] of INTEGER  {request list data}
  54684.                END;
  54685.  
  54686. If an entry is not present in srcTable, then that position of the requestList is set
  54687. to colReqErr, and that position of resultTable has random values returned. If one or
  54688. more entries are not found, then an error code is posted to QDError; however, for
  54689. every entry in selection which is not colReqErr, the values in resultTable are valid.
  54690. Note that srcTable and selection are assumed to have the same number of entries.
  54691.  
  54692. SaveEntries optionally allows NIL as its source color table parameter. If NIL is
  54693. used, the current device’s color table is used as the source. The output of SaveEntries
  54694. is the same as the input for RestoreEntries, except for the order.
  54695.  
  54696. æKY qd
  54697. æFc Quickdraw.h
  54698. æT struct
  54699. æD extern struct  {
  54700. char privates[76];
  54701. long randSeed;
  54702. BitMap screenBits;
  54703. Cursor arrow;
  54704. Pattern dkGray;
  54705. Pattern ltGray;
  54706. Pattern gray;
  54707. Pattern black;
  54708. Pattern white;
  54709. GrafPtr thePort;
  54710. }qd;
  54711.  
  54712.  
  54713.  
  54714. æC 
  54715.  
  54716. æKY InitGraf
  54717. æFc Quickdraw.h
  54718. æT Function
  54719. æTN A86E
  54720. æD pascal void InitGraf(void * globalPtr)
  54721.     = 0xA86E; 
  54722. æDT InitGraf((void *) globalPtr);
  54723. æMM
  54724. æRI I-162, P-31, 63, 95, 101, 107, 112, 118, 174
  54725. æC  
  54726. _______________________________________________________________________________
  54727.  
  54728. »GrafPort Routines
  54729.  
  54730. PROCEDURE InitGraf (globalPtr:  Ptr);
  54731.  
  54732. Call InitGraf once and only once at the beginning of your program to initialize
  54733. QuickDraw. It initializes the global variables listed below (as well as some private
  54734. global variables for its own internal use).
  54735.  
  54736.   Variable      Type       Initial setting
  54737.  
  54738.   thePort       GrafPtr    NIL
  54739.   white         Pattern    An all-white pattern
  54740.   black         Pattern    An all-black pattern
  54741.   gray          Pattern    A 50% gray pattern
  54742.   ltGray        Pattern    A 25% gray pattern
  54743.   dkGray        Pattern    A 75% gray pattern
  54744.   arrow         Cursor     The standard arrow cursor
  54745.   screenBits    BitMap     The entire screen
  54746.   randSeed      LONGINT    1
  54747.  
  54748. You must pass, in the globalPtr parameter, a pointer to the first QuickDraw global
  54749. variable, thePort. From Pascal programs, you should always pass @thePort for globalPtr.
  54750.  
  54751. Assembly-language note:  The QuickDraw global variables are stored in reverse
  54752.                          order, from high to low memory, and require the number
  54753.                          of bytes specified by the global constant grafSize.
  54754.                          Most development systems (including the Lisa Workshop)
  54755.                          preallocate space for these globals immediately below
  54756.                          the location pointed to by register A5. Since thePort
  54757.                          is four bytes, you would pass the globalPtr parameter
  54758.                          as follows:
  54759.  
  54760.                            PEA        -4(A5)
  54761.                            _InitGraf
  54762.  
  54763.                          InitGraf stores this pointer to thePort in the
  54764.                          location pointed to by A5. This value is used as a
  54765.                          base address when accessing the other QuickDraw global
  54766.                          variables, which are accessed using negative offsets
  54767.                          (the offsets have the same names as the Pascal global
  54768.                          variables). For example:
  54769.  
  54770.                            MOVE.L  (A5),A0           ;point to first
  54771.                                                      ; QuickDraw global
  54772.                            MOVE.L  randSeed(A0),A1   ;get global variable
  54773.                                                      ; randSeed
  54774.  
  54775. Note:  To initialize the cursor, call InitCursor (described under
  54776.        “Cursor-Handling Routines” below).
  54777.  
  54778. æKY OpenPort
  54779. æFc Quickdraw.h
  54780. æT Function
  54781. æTN A86F
  54782. æD pascal void OpenPort(GrafPtr port)
  54783.     = 0xA86F; 
  54784. æDT OpenPort((GrafPtr) port);
  54785. æMM
  54786. æRT 155,194
  54787. æRI I-163
  54788. æC  
  54789. OpenPort allocates space for the given grafPort’s visRgn and clipRgn, initializes the
  54790. fields of the grafPort as indicated below, and makes the grafPort the current port
  54791. (by calling SetPort). OpenPort is called by the Window Manager when you create a
  54792. window, and you normally won’t call it yourself. If you do call OpenPort, you can
  54793. create the grafPtr with the Memory Manager procedure NewPtr or reserve the space on
  54794. the stack (with a variable of type GrafPort).
  54795.  
  54796.   Field         Type          Initial setting
  54797.  
  54798.   device        INTEGER       0 (the screen)
  54799.   portBits      BitMap        screenBits
  54800.   portRect      Rect          screenBits.bounds
  54801.   visRgn        RgnHandle     handle to a rectangular region coincident
  54802.                               with screenBits.bounds
  54803.   clipRgn       RgnHandle     handle to the rectangular region
  54804.                               (–32767,–32767) (32767,32767)
  54805.   bkPat         Pattern       white
  54806.   fillPat       Pattern       black
  54807.   pnLoc         Point         (0,0)
  54808.   pnSize        Point         (1,1)
  54809.   pnMode        INTEGER       patCopy
  54810.   pnPat         Pattern       black
  54811.   pnVis         INTEGER       0 (visible)
  54812.   txFont        INTEGER       0 (system font)
  54813.   txFace        Style         plain
  54814.   txMode        INTEGER       srcOr
  54815.   txSize        INTEGER       0 (system font size)
  54816.   spExtra       Fixed         0
  54817.   fgColor       LONGINT       blackColor
  54818.   bkColor       LONGINT       whiteColor
  54819.   colrBit       INTEGER       0
  54820.   patStretch    INTEGER       0
  54821.   picSave       Handle        NIL
  54822.   rgnSave       Handle        NIL
  54823.   polySave      Handle        NIL
  54824.   grafProcs     QDProcsPtr    NIL
  54825.  
  54826. æKY InitPort
  54827. æFc Quickdraw.h
  54828. æT Function
  54829. æTN A86D
  54830. æD pascal void InitPort(GrafPtr port)
  54831.     = 0xA86D; 
  54832. æDT InitPort((GrafPtr) port);
  54833. æMM
  54834. æRI I-164
  54835. æC  
  54836.  
  54837. Given a pointer to a grafPort that’s been opened with OpenPort, InitPort reinitializes
  54838. the fields of the grafPort and makes it the current port. It’s unlikely that you’ll
  54839. ever have a reason to call this procedure.
  54840.  
  54841. Note:  InitPort does everything OpenPort does except allocate space for
  54842.        the visRgn and clipRgn.
  54843.  
  54844. æKY ClosePort
  54845. æFc Quickdraw.h
  54846. æT Function
  54847. æTN A87D
  54848. æD pascal void ClosePort(GrafPtr port)
  54849.     = 0xA87D; 
  54850. æDT ClosePort((GrafPtr) port);
  54851. æMM
  54852. æRI I-164
  54853. æC  
  54854. ClosePort releases the memory occupied by the given grafPort’s visRgn and clipRgn.
  54855. When you’re completely through with a grafPort, call this procedure and then dispose
  54856. of the grafPort with the Memory Manager procedure DisposPtr
  54857. (if it was allocated with NewPtr). This is normally done for you when you call the
  54858. Window Manager to close or dispose of a window.
  54859.  
  54860. Warning:  If ClosePort isn’t called before a grafPort is disposed of, the
  54861.           memory used by the visRgn and clipRgn will be unrecoverable.
  54862.  
  54863. Warning:
  54864.  
  54865.     After calling ClosePort, be sure not use any copies of
  54866.     the visRgn or clipRgn handles that you may have made.
  54867.  
  54868. æKY SetPort
  54869. æFc Quickdraw.h
  54870. æT Function
  54871. æTN A873
  54872. æD pascal void SetPort(GrafPtr port)
  54873.     = 0xA873; 
  54874. æDT SetPort((GrafPtr) port);
  54875. æRI I-165, P-63, 64, 67, 87, 97, 180
  54876. æC 
  54877. SetPort makes the specified grafPort the current port.
  54878.  
  54879. Note:  Only SetPort (and OpenPort and InitPort, which call it) changes the
  54880.        current port. All the other routines in the Toolbox and Operating
  54881.        System (even those that call SetPort, OpenPort, or InitPort) leave
  54882.        the current port set to what it was when they were called.
  54883.  
  54884. The global variable thePort always points to the current port. All QuickDraw drawing
  54885. routines affect the bit map thePort^.portBits and use the local coordinate system of
  54886. thePort^.
  54887.  
  54888. Each port has its own pen and text characteristics, which remain unchanged when the
  54889. port isn’t selected as the current port.
  54890.  
  54891. æKY GetPort
  54892. æFc Quickdraw.h
  54893. æT Function
  54894. æTN A874
  54895. æD pascal void GetPort(GrafPtr *port)
  54896.     = 0xA874; 
  54897. æDT GetPort((GrafPtr *) port);
  54898. æRI I-165, P-63, 67, 97, 173
  54899. æC 
  54900. GetPort returns a pointer to the current grafPort. This pointer is also available
  54901. through the global variable thePort, but you may prefer to use GetPort for better
  54902. readability of your program text. For example, a procedure could do a GetPort(savePort)
  54903. before setting its own grafPort and a
  54904. SetPort(savePort) afterwards to restore the previous port.
  54905.  
  54906. æKY GrafDevice
  54907. æFc Quickdraw.h
  54908. æT Function
  54909. æTN A872
  54910. æD pascal void GrafDevice(short device)
  54911.     = 0xA872; 
  54912. æDT GrafDevice((short) device);
  54913. æRI I-165
  54914. æC  
  54915. GrafDevice sets the device field of the current grafPort to the given value, which
  54916. consists of device-specific information that’s used by the Font Manager to achieve
  54917. the best possible results when drawing text in the grafPort. The initial value of the
  54918. device field is 0, for best results on output to the screen. For more information,
  54919. see the Font Manager chapter.
  54920.  
  54921. Note:  This field is used for communication between QuickDraw and the Font
  54922.        Manager; normally you won’t set it yourself.
  54923.  
  54924. æKY SetPortBits
  54925. æFc Quickdraw.h
  54926. æT Function
  54927. æTN A875
  54928. æD pascal void SetPortBits(const BitMap *bm)
  54929.     = 0xA875; 
  54930. æDT SetPortBits((const BitMap *) bm);
  54931. æRI I-165
  54932. æC  
  54933. Assembly-language note:  The macro you invoke to call SetPortBits from
  54934.                          assembly language is named _SetPBits.
  54935.  
  54936. SetPortBits sets the portBits field of the current grafPort to any previously defined
  54937. bit map. This allows you to perform all normal drawing and calculations on a buffer
  54938. other than the screen—for example, a small off-screen image for later “stamping” onto
  54939. the screen (with the CopyBits procedure, described under
  54940. “Bit Transfer Operations” below).
  54941.  
  54942. Remember to prepare all fields of the bit map before you call SetPortBits.
  54943.  
  54944. æKY PortSize
  54945. æFc Quickdraw.h
  54946. æT Function
  54947. æTN A876
  54948. æD pascal void PortSize(short width,short height)
  54949.     = 0xA876; 
  54950. æDT PortSize((short) width,(short) height);
  54951. æRI I-165
  54952. æC  
  54953. PortSize changes the size of the current grafPort’s portRect. This does not affect
  54954. the screen; it merely changes the size of the “active area” of the grafPort.
  54955.  
  54956. Note:  This procedure is normally called only by the Window Manager.
  54957.  
  54958. The top left corner of the portRect remains at its same location; the width and
  54959. height of the portRect are set to the given width and height. In other words, PortSize
  54960. moves the bottom right corner of the portRect to a position relative to the top left
  54961. corner.
  54962.  
  54963. PortSize doesn’t change the clipRgn or the visRgn, nor does it affect the local
  54964. coordinate system of the grafPort:  It changes only the portRect’s width and height.
  54965. Remember that all drawing occurs only in the intersection of the portBits.bounds and
  54966. the portRect, clipped to the visRgn and the clipRgn.
  54967.  
  54968. æKY MovePortTo
  54969. æFc Quickdraw.h
  54970. æT Function
  54971. æTN A877
  54972. æD pascal void MovePortTo(short leftGlobal,short topGlobal)
  54973.     = 0xA877; 
  54974. æDT MovePortTo((short) leftGlobal,(short) topGlobal);
  54975. æRI I-166
  54976. æC  
  54977. MovePortTo changes the position of the current grafPort’s portRect. This does not
  54978. affect the screen; it merely changes the location at which subsequent drawing inside
  54979. the port will appear.
  54980.  
  54981. Note:  This procedure is normally called only by the Window Manager
  54982.        and the System Error Handler.
  54983.  
  54984. The leftGlobal and topGlobal parameters set the distance between the top left corner
  54985. of portBits.bounds and the top left corner of the new portRect.
  54986.  
  54987. Like PortSize, MovePortTo doesn’t change the clipRgn or the visRgn, nor does it
  54988. affect the local coordinate system of the grafPort.
  54989.  
  54990. æKY SetOrigin
  54991. æFc Quickdraw.h
  54992. æT Function
  54993. æTN A878
  54994. æD pascal void SetOrigin(short h,short v)
  54995.     = 0xA878; 
  54996. æDT SetOrigin((short) h,(short) v);
  54997. æRT 72
  54998. æRI I-166, N72-2, P-76, 180
  54999. æC  
  55000. SetOrigin changes the local coordinate system of the current grafPort. This does not
  55001. affect the screen; it does, however, affect where subsequent drawing inside the port
  55002. will appear.
  55003.  
  55004. The h and v parameters set the coordinates of the top left corner of the portRect.
  55005. All other coordinates are calculated from this point; SetOrigin also offsets the
  55006. coordinates of the portBits.bounds rectangle and the visRgn. Relative distances among
  55007. elements in the port remain the same; only their absolute local coordinates change.
  55008. All subsequent drawing and calculation routines use the new coordinate system.
  55009.  
  55010. Note:  SetOrigin does not offset the coordinates of the clipRgn or the pen;
  55011.        the pen and clipRgn “stick” to the coordinate system, and therefore
  55012.        change position on the screen (unlike the portBits.bounds, portRect,
  55013.        and visRgn, which “stick” to the screen, and don’t change position).
  55014.        See the “Coordinates in GrafPorts” section for an illustration.
  55015.  
  55016. SetOrigin is useful for readjusting the coordinate system after a scrolling operation.
  55017. (See ScrollRect under “Bit Transfer Operations” below.)
  55018.  
  55019. Note:  All other routines in the Toolbox and Operating System preserve the
  55020.        local coordinate system of the current grafPort.
  55021.  
  55022. æKY SetClip
  55023. æFc Quickdraw.h
  55024. æT Function
  55025. æTN A879
  55026. æD pascal void SetClip(RgnHandle rgn)
  55027.     = 0xA879; 
  55028. æDT SetClip((RgnHandle) rgn);
  55029. æMM
  55030. æRI I-166
  55031. æC  
  55032. SetClip changes the clipping region of the current grafPort to a region that’s equivalent
  55033. to the given region. Note that this doesn’t change the region handle, but affects the
  55034. clipping region itself. Since SetClip makes a copy of the given region, any subsequent
  55035. changes you make to that region will not affect the clipping region of the port.
  55036.  
  55037. You can set the clipping region to any arbitrary region, to aid you in drawing inside
  55038. the grafPort. The initial clipRgn is an arbitrarily large rectangle.
  55039.  
  55040. Note:  All routines in the Toolbox and Operating System preserve the
  55041.        current clipRgn.
  55042.  
  55043. æKY GetClip
  55044. æFc Quickdraw.h
  55045. æT Function
  55046. æTN A87A
  55047. æD pascal void GetClip(RgnHandle rgn)
  55048.     = 0xA87A; 
  55049. æDT GetClip((RgnHandle) rgn);
  55050. æMM
  55051. æRI I-167
  55052. æC  
  55053. GetClip changes the given region to a region that’s equivalent to the clipping region
  55054. of the current grafPort. This is the reverse of what SetClip does. Like SetClip, it
  55055. doesn’t change the region handle. GetClip and SetClip are used to preserve the current
  55056. clipRgn (they’re analogous to GetPort and SetPort).
  55057.  
  55058. æKY ClipRect
  55059. æFc Quickdraw.h
  55060. æT Function
  55061. æTN A87B
  55062. æD pascal void ClipRect(const Rect *r)
  55063.     = 0xA87B; 
  55064. æDT ClipRect((const Rect *) r);
  55065. æMM
  55066. æRT 59
  55067. æRI I-167
  55068. æC  
  55069. ClipRect changes the clipping region of the current grafPort to a rectangle that’s
  55070. equivalent to the given rectangle. Note that this doesn’t change the region handle,
  55071. but affects the clipping region itself.
  55072.  
  55073. æKY BackPat
  55074. æFc Quickdraw.h
  55075. æT Function
  55076. æTN A87C
  55077. æD pascal void BackPat(Pattern pat)
  55078.     = 0xA87C; 
  55079. æDT BackPat((Pattern) pat);
  55080. æMM
  55081. æRI I-167
  55082. æC  
  55083. BackPat sets the background pattern of the current grafPort to the given pattern. The
  55084. background pattern is used in ScrollRect and in all QuickDraw routines that perform
  55085. an “erase” operation.
  55086.  
  55087. æKY InitCursor
  55088. æFc Quickdraw.h
  55089. æT Function
  55090. æTN A850
  55091. æD pascal void InitCursor(void)
  55092.     = 0xA850; 
  55093. æDT InitCursor()(void);
  55094. æRI I-167, P-84, 174
  55095. æC 
  55096. InitCursor sets the current cursor to the standard arrow and sets the cursor level to
  55097. 0, making the cursor visible. The cursor level keeps track of the number of times the
  55098. cursor has been hidden to compensate for nested calls to HideCursor and ShowCursor,
  55099. explained below.
  55100.  
  55101. æKY SetCursor
  55102. æFc Quickdraw.h
  55103. æT Function
  55104. æTN A851
  55105. æD pascal void SetCursor(const Cursor *crsr)
  55106.     = 0xA851; 
  55107. æDT SetCursor((const Cursor *) crsr);
  55108. æRI I-167, P-84, 179
  55109. æC  
  55110. SetCursor sets the current cursor to the given cursor. If the cursor is hidden, it
  55111. remains hidden and will attain the new appearance when it’s uncovered; if the cursor
  55112. is already visible, it changes to the new appearance immediately.
  55113.  
  55114. The cursor image is initialized by InitCursor to the standard arrow, visible on the
  55115. screen.
  55116.  
  55117. Note:  You’ll normally get a cursor from a resource file, by calling the
  55118.        Toolbox Utility function GetCursor, and then doubly dereference the
  55119.        handle it returns.
  55120.  
  55121. æKY HideCursor
  55122. æFc Quickdraw.h
  55123. æT Function
  55124. æTN A852
  55125. æD pascal void HideCursor(void)
  55126.     = 0xA852; 
  55127. æDT HideCursor()(void);
  55128. æRI I-168, P-84, 174
  55129. æC 
  55130. HideCursor removes the cursor from the screen, restoring the bits under it, and
  55131. decrements the cursor level (which InitCursor initialized to 0). Every call to HideCursor
  55132. should be balanced by a subsequent call to ShowCursor.
  55133.  
  55134. Note:  See also the description of the Toolbox Utility procedure ShieldCursor.
  55135.  
  55136. æKY ShowCursor
  55137. æFc Quickdraw.h
  55138. æT Function
  55139. æTN A853
  55140. æD pascal void ShowCursor(void)
  55141.     = 0xA853; 
  55142. æDT ShowCursor()(void);
  55143. æRI I-168, P-84, 181
  55144. æC  
  55145. ShowCursor increments the cursor level, which may have been decremented by HideCursor,
  55146. and displays the cursor on the screen if the level becomes 0. A call to ShowCursor
  55147. should balance each previous call to HideCursor. The level isn’t incremented beyond
  55148. 0, so extra calls to ShowCursor have no effect.
  55149.  
  55150. The low-level interrupt-driven routines link the cursor with the mouse position, so
  55151. that if the cursor level is 0 (visible), the cursor automatically follows the mouse.
  55152. You don’t need to do anything but a ShowCursor to have the cursor track the mouse.
  55153.  
  55154. If the cursor has been changed (with SetCursor) while hidden, ShowCursor presents the
  55155. new cursor.
  55156.  
  55157. æKY ObscureCursor
  55158. æFc Quickdraw.h
  55159. æT Function
  55160. æTN A856
  55161. æD pascal void ObscureCursor(void)
  55162.     = 0xA856; 
  55163. æDT ObscureCursor()(void);
  55164. æRI I-168, P-84, 178
  55165. æC  
  55166. ObscureCursor hides the cursor until the next time the mouse is moved. It’s normally
  55167. called when the user begins to type. Unlike HideCursor, it has no effect on the
  55168. cursor level and must not be balanced by a call to ShowCursor.
  55169.  
  55170. æKY HidePen
  55171. æFc Quickdraw.h
  55172. æT Function
  55173. æTN A896
  55174. æD pascal void HidePen(void)
  55175.     = 0xA896; 
  55176. æDT HidePen()(void);
  55177. æRI I-168
  55178. æC  
  55179. HidePen decrements the current grafPort’s pnVis field, which is initialized to 0 by
  55180. OpenPort; whenever pnVis is negative, the pen doesn’t draw on the screen. PnVis keeps
  55181. track of the number of times the pen has been hidden to compensate for nested calls
  55182. to HidePen and ShowPen (below). Every call to HidePen should be balanced by a subsequent
  55183. call to ShowPen. HidePen is called by OpenRgn, OpenPicture, and OpenPoly so that you
  55184. can define regions, pictures, and polygons without drawing on the screen.
  55185.  
  55186. æKY ShowPen
  55187. æFc Quickdraw.h
  55188. æT Function
  55189. æTN A897
  55190. æD pascal void ShowPen(void)
  55191.     = 0xA897; 
  55192. æDT ShowPen()(void);
  55193. æRI I-168
  55194. æC  
  55195. ShowPen increments the current grafPort’s pnVis field, which may have been decremented
  55196. by HidePen; if pnVis becomes 0, QuickDraw resumes drawing on the screen. Extra calls
  55197. to ShowPen will increment pnVis beyond 0, so every call to ShowPen should be balanced
  55198. by a call to HidePen. ShowPen is called by CloseRgn, ClosePicture, and ClosePoly.
  55199.  
  55200. æKY GetPen
  55201. æFc Quickdraw.h
  55202. æT Function
  55203. æTN A89A
  55204. æD pascal void GetPen(Point *pt)
  55205.     = 0xA89A; 
  55206. æDT GetPen((Point *) pt);
  55207. æRI I-169, P-78, 173
  55208. æC  
  55209. GetPen returns the current pen location, in the local coordinates of the current
  55210. grafPort.
  55211.  
  55212. æKY GetPenState
  55213. æFc Quickdraw.h
  55214. æT Function
  55215. æTN A898
  55216. æD pascal void GetPenState(PenState *pnState)
  55217.     = 0xA898; 
  55218. æDT GetPenState((PenState *) pnState);
  55219. æRI I-169, P-78, 173
  55220. æC  
  55221. GetPenState saves the pen location, size, pattern, and mode in pnState, to be restored
  55222. later with SetPenState. This is useful when calling subroutines that operate in the
  55223. current port but must change the graphics pen:  Each such procedure can save the
  55224. pen’s state when it’s called, do whatever it needs to do, and restore the previous
  55225. pen state immediately before returning. The PenState data type is defined as follows:
  55226.  
  55227. TYPE  PenState  =  RECORD
  55228.                      pnLoc:   Point;    {pen location}
  55229.                      pnSize:  Point;    {pen size}
  55230.                      pnMode:  INTEGER;  {pen's transfer mode}
  55231.                      pnPat:   Pattern   {pen pattern}
  55232.                    END;
  55233.  
  55234. æKY SetPenState
  55235. æFc Quickdraw.h
  55236. æT Function
  55237. æTN A899
  55238. æD pascal void SetPenState(const PenState *pnState)
  55239.     = 0xA899; 
  55240. æDT SetPenState((const PenState *) pnState);
  55241. æRI I-169, P-180
  55242. æC  
  55243. SetPenState sets the pen location, size, pattern, and mode in the current grafPort to
  55244. the values stored in pnState. This is usually called at the end of a procedure that
  55245. has altered the pen parameters and wants to restore them to their state at the beginning
  55246. of the procedure. (See GetPenState, above.)
  55247.  
  55248. æKY PenSize
  55249. æFc Quickdraw.h
  55250. æT Function
  55251. æTN A89B
  55252. æD pascal void PenSize(short width,short height)
  55253.     = 0xA89B; 
  55254. æDT PenSize((short) width,(short) height);
  55255. æRI I-169, P-79, 179
  55256. æC 
  55257. PenSize sets the dimensions of the graphics pen in the current grafPort. All subsequent
  55258. calls to Line, LineTo, and the procedures that draw framed shapes in the current
  55259. grafPort will use the new pen dimensions.
  55260.  
  55261. The pen dimensions can be accessed in the variable thePort^.pnSize, which is of type
  55262. Point. If either of the pen dimensions is set to a negative value, the pen assumes
  55263. the dimensions (0,0) and no drawing is performed. For a discussion of how the pen
  55264. draws, see the “General Discussion of Drawing” section.
  55265.  
  55266. æKY PenMode
  55267. æFc Quickdraw.h
  55268. æT Function
  55269. æTN A89C
  55270. æD pascal void PenMode(short mode)
  55271.     = 0xA89C; 
  55272. æDT PenMode((short) mode);
  55273. æRI I-169, P-79, 178
  55274. æC 
  55275. PenMode sets the transfer mode through which the pen pattern is transferred onto the
  55276. bit map when lines or shapes are drawn in the current grafPort. The mode may be any
  55277. one of the pattern transfer modes:
  55278.  
  55279.   patCopy    notPatCopy
  55280.   patOr      notPatOr
  55281.   patXor     notPatXor
  55282.   patBic     notPatBic
  55283.  
  55284. If the mode is one of the source transfer modes (or negative), no drawing is performed.
  55285. The current pen mode can be accessed in the variable thePort^.pnMode. The initial pen
  55286. mode is patCopy, in which the pen pattern is copied directly to the bit map.
  55287.  
  55288. æKY PenPat
  55289. æFc Quickdraw.h
  55290. æT Function
  55291. æTN A89D
  55292. æD pascal void PenPat(Pattern pat)
  55293.     = 0xA89D; 
  55294. æDT PenPat((Pattern) pat);
  55295. æMM
  55296. æRI I-170, P-79, 179
  55297. æC 
  55298. PenPat sets the pattern that’s used by the pen in the current grafPort. The standard
  55299. patterns white, black, gray, ltGray, and dkGray are predefined; the initial pen
  55300. pattern is black. The current pen pattern can be accessed in the variable thePort^.pnPat,
  55301. and this value can be assigned to any other variable of type Pattern.
  55302.  
  55303. æKY PenNormal
  55304. æFc Quickdraw.h
  55305. æT Function
  55306. æTN A89E
  55307. æD pascal void PenNormal(void)
  55308.     = 0xA89E; 
  55309. æDT PenNormal()(void);
  55310. æMM
  55311. æRI I-170, P-79, 179
  55312. æC  
  55313. PenNormal resets the initial state of the pen in the current grafPort, as follows:
  55314.  
  55315.   Field     Setting
  55316.  
  55317.   pnSize    (1,1)
  55318.   pnMode    patCopy
  55319.   pnPat     black
  55320.  
  55321. The pen location is not changed.
  55322.  
  55323. æKY MoveTo
  55324. æFc Quickdraw.h
  55325. æT Function
  55326. æTN A893
  55327. æD pascal void MoveTo(short h,short v)
  55328.     = 0xA893; 
  55329. æDT MoveTo((short) h,(short) v);
  55330. æRI I-170, P-79, 177
  55331. æC 
  55332. MoveTo moves the pen to location (h,v) in the local coordinates of the current grafPort.
  55333. No drawing is performed.
  55334.  
  55335. æKY Move
  55336. æFc Quickdraw.h
  55337. æT Function
  55338. æTN A894
  55339. æD pascal void Move(short dh,short dv)
  55340.     = 0xA894; 
  55341. æDT Move((short) dh,(short) dv);
  55342. æRI I-170, P-79, 176
  55343. æC 
  55344. This procedure moves the pen a distance of dh horizontally and dv vertically from its
  55345. current location; it calls MoveTo(h+dh,v+dv), where (h,v) is the current location.
  55346. The positive directions are to the right and down. No drawing is performed.
  55347.  
  55348. æKY LineTo
  55349. æFc Quickdraw.h
  55350. æT Function
  55351. æTN A891
  55352. æD pascal void LineTo(short h,short v)
  55353.     = 0xA891; 
  55354. æDT LineTo((short) h,(short) v);
  55355. æMM
  55356. æRI I-170, P-79, 87, 175
  55357. æC 
  55358. LineTo draws a line from the current pen location to the location specified (in local
  55359. coordinates) by h and v. The new pen location is (h,v) after the line is drawn. See
  55360. the “General Discussion of Drawing” section.
  55361.  
  55362. If a region or polygon is open and being formed, its outline is infinitely thin and
  55363. is not affected by the pnSize, pnMode, or pnPat. (See OpenRgn and OpenPoly.)
  55364.  
  55365. æKY Line
  55366. æFc Quickdraw.h
  55367. æT Function
  55368. æTN A892
  55369. æD pascal void Line(short dh,short dv)
  55370.     = 0xA892; 
  55371. æDT Line((short) dh,(short) dv);
  55372. æMM
  55373. æRI I-171
  55374. æC 
  55375. This procedure draws a line to the location that’s a distance of dh horizontally and
  55376. dv vertically from the current pen location; it calls
  55377. LineTo(h+dh,v+dv), where (h,v) is the current location. The positive directions are
  55378. to the right and down. The pen location becomes the coordinates of the end of the
  55379. line after the line is drawn. See the “General Discussion of Drawing” section.
  55380.  
  55381. If a region or polygon is open and being formed, its outline is infinitely thin and
  55382. is not affected by the pnSize, pnMode, or pnPat. (See OpenRgn and OpenPoly.)
  55383.  
  55384. æKY TextFont
  55385. æFc Quickdraw.h
  55386. æT Function
  55387. æTN A887
  55388. æD pascal void TextFont(short font)
  55389.     = 0xA887; 
  55390. æDT TextFont((short) font);
  55391. æRI I-171, P-82, 184
  55392. æC  
  55393. TextFont sets the current grafPort’s font (thePort^.txFont) to the given font number.
  55394. The initial font number is 0, which represents the system font.
  55395.  
  55396. æKY TextFace
  55397. æFc Quickdraw.h
  55398. æT Function
  55399. æTN A888
  55400. æD pascal void TextFace(Short face)
  55401.     = 0xA888; 
  55402. æDT TextFace((Short) face);
  55403. æRI I-171, P-82, 184
  55404. æC  
  55405. TextFace sets the current grafPort’s character style (thePort^.txFace). The Style
  55406. data type allows you to specify a set of one or more of the following predefined
  55407. constants:  bold, italic, underline, outline, shadow, condense, and extend. For
  55408. example:
  55409.  
  55410.   TextFace([bold]);                    {bold}
  55411.   TextFace([bold,italic]);             {bold and italic}
  55412.   TextFace(thePort^.txFace+[bold]);    {whatever it was plus bold}
  55413.   TextFace(thePort^.txFace-[bold]);    {whatever it was but not bold}
  55414.   TextFace([]);                        {plain text}
  55415.  
  55416. æKY TextMode
  55417. æFc Quickdraw.h
  55418. æT Function
  55419. æTN A889
  55420. æD pascal void TextMode(short mode)
  55421.     = 0xA889; 
  55422. æDT TextMode((short) mode);
  55423. æRI I-171, P-82, 184
  55424. æC  
  55425. TextMode sets the current grafPort’s transfer mode for drawing text
  55426. (thePort^.txMode). The mode should be srcOr, srcXor, or srcBic. The initial transfer
  55427. mode for drawing text is srcOr.
  55428.  
  55429. æKY TextSize
  55430. æFc Quickdraw.h
  55431. æT Function
  55432. æTN A88A
  55433. æD pascal void TextSize(short size)
  55434.     = 0xA88A; 
  55435. æDT TextSize((short) size);
  55436. æRI I-171, P-82, 184
  55437. æC  
  55438. TextSize sets the current grafPort’s font size (thePort^.txSize) to the given number
  55439. of points. Any size may be specified, but the result will look best if the Font
  55440. Manager has the font in that size (otherwise it will scale a size it does have). The
  55441. next best result will occur if the given size is an even multiple of a size available
  55442. for the font. If 0 is specified, the system font size (12 points) will be used. The
  55443. initial txSize setting is 0.
  55444.  
  55445. æKY SpaceExtra
  55446. æFc Quickdraw.h
  55447. æT Function
  55448. æTN A88E
  55449. æD pascal void SpaceExtra(Fixed extra)
  55450.     = 0xA88E; 
  55451. æDT SpaceExtra((Fixed) extra);
  55452. æRI I-172, P-82, 182
  55453. æC  
  55454. SpaceExtra sets the current grafPort’s spExtra field, which specifies the average
  55455. number of pixels by which to widen each space in a line of text. This is useful when
  55456. text is being fully justified (that is, aligned with both a left and a right margin).
  55457. The initial spExtra setting is 0.
  55458.  
  55459. SpaceExtra will also accept a negative parameter, but be careful not to narrow spaces
  55460. so much that the text is unreadable.
  55461.  
  55462. æKY DrawChar
  55463. æFc Quickdraw.h
  55464. æT Function
  55465. æTN A883
  55466. æD pascal void DrawChar(short ch)
  55467.     = 0xA883; 
  55468. æDT DrawChar((short) ch);
  55469. æMM
  55470. æRT 26
  55471. æRI I-172, N26, P-83, 169
  55472. æC  
  55473. DrawChar places the given character to the right of the pen location, with the left
  55474. end of its base line at the pen’s location, and advances the pen accordingly. If the
  55475. character isn’t in the font, the font’s missing symbol is drawn.
  55476.  
  55477. Note:  If you’re drawing a series of characters, it’s faster to make one
  55478.        DrawString or DrawText call rather than a series of DrawChar calls.
  55479.  
  55480. æKY DrawString
  55481. æFc Quickdraw.h
  55482. æT Function
  55483. æTN A884
  55484. æD pascal void DrawString(const Str255 s)
  55485.     = 0xA884; 
  55486. æDT DrawString((const Str255) s);
  55487. æMM
  55488. æRT 26
  55489. æRI I-172, N26, P-83, 170
  55490. æC  
  55491. DrawString calls DrawChar for each character in the given string. The string is
  55492. placed beginning at the current pen location and extending right. No formatting (such
  55493. as carriage returns and line feeds) is performed by QuickDraw. The pen location ends
  55494. up to the right of the last character in the string.
  55495.  
  55496. Warning:  QuickDraw temporarily stores on the stack all of the text you
  55497.           ask it to draw, even if the text will be clipped. When drawing
  55498.           large font sizes or complex style variations, it’s best to draw
  55499.           only what will be visible on the screen. You can determine how
  55500.           many characters will actually fit on the screen by calling the
  55501.           StringWidth function before calling DrawString.
  55502.  
  55503. æKY DrawText
  55504. æFc Quickdraw.h
  55505. æT Function
  55506. æTN A885
  55507. æD pascal void DrawText(Ptr textBuf,short firstByte,short byteCount)
  55508.     = 0xA885; 
  55509. æDT DrawText((Ptr) textBuf,(short) firstByte,(short) byteCount);
  55510. æMM
  55511. æRT 207
  55512. æRI I-172, P-83, 170
  55513. æC  
  55514. DrawText calls DrawChar for each character in the arbitrary structure in memory
  55515. specified by textBuf, starting firstByte bytes into the structure and continuing for
  55516. byteCount bytes (firstByte starts at 0). The text is placed beginning at the current
  55517. pen location and extending right. No formatting (such as carriage returns and line
  55518. feeds) is performed by QuickDraw. The pen location ends up to the right of the last
  55519. character in the string.
  55520.  
  55521. Warning:  Inside a picture definition, DrawText can’t have a byteCount
  55522.           greater than 255.
  55523.  
  55524. Note:  You can determine how many characters will actually fit on the
  55525.        screen by calling the TextWidth function before calling DrawText.
  55526.        (See the warning under DrawString above.)
  55527.  
  55528. æKY CharWidth
  55529. æFc Quickdraw.h
  55530. æT Function
  55531. æTN A88D
  55532. æD pascal short CharWidth(short ch)
  55533.     = 0xA88D; 
  55534. æDT short myVariable = CharWidth((short) ch);
  55535. æMM
  55536. æRT 26, 82 
  55537. æRI I-173, N26, N82-2
  55538. æC 
  55539. CharWidth returns the character width of the specified character, that is, the value
  55540. that will be added to the pen horizontal coordinate if the specified character is
  55541. drawn. CharWidth includes the effects of the stylistic variations set with TextFace;
  55542. if you change these after determining the character width but before actually drawing
  55543. the character, the predetermined width may not be correct. If the character is a
  55544. space, CharWidth also includes the effect of SpaceExtra.
  55545.  
  55546. æKY StringWidth
  55547. æFc Quickdraw.h
  55548. æT Function
  55549. æTN A88C
  55550. æD pascal short StringWidth(const Str255 s)
  55551.     = 0xA88C; 
  55552. æDT short myVariable = StringWidth((const Str255) s);
  55553. æMM
  55554. æRT 26
  55555. æRI I-173, N26
  55556. æC  
  55557. StringWidth returns the width of the given text string, which it calculates by adding
  55558. the CharWidths of all the characters in the string (see above).
  55559.  
  55560. æKY TextWidth
  55561. æFc Quickdraw.h
  55562. æT Function
  55563. æTN A886
  55564. æD pascal short TextWidth(Ptr textBuf,short firstByte,short byteCount)
  55565.     = 0xA886; 
  55566. æDT short myVariable = TextWidth((Ptr) textBuf,(short) firstByte,(short) byteCount);
  55567. æMM
  55568. æRI I-173, N131-3
  55569. æC  
  55570. TextWidth returns the width of the text stored in the arbitrary structure in memory
  55571. specified by textBuf, starting firstByte bytes into the structure and continuing for
  55572. byteCount bytes (firstByte starts at 0). TextWidth calculates the width by adding the
  55573. CharWidths of all the characters in the text. (See CharWidth, above.)
  55574.  
  55575. æKY MeasureText
  55576. æFc Quickdraw.h
  55577. æT Function
  55578. æTN A837
  55579. æD pascal void MeasureText(short count,Ptr textAddr,Ptr charLocs)
  55580.     = 0xA837; 
  55581. æDT MeasureText((short) count,(Ptr) textAddr,(Ptr) charLocs);
  55582. æMM
  55583. æRI IV-25
  55584. æC  
  55585. This procedure is designed to improve performance in specialized applications such as
  55586. word processors by providing an array version of the TextWidth function; it’s like
  55587. calling TextWidth repeatedly for a given set of characters. TextAddr points to an
  55588. arbitrary piece of text in memory, and count specifies how many characters are to be
  55589. measured.
  55590.  
  55591. MeasureText moves along the string and, for each character, computes the distance
  55592. from TextAddr to the right edge of the character. CharLocs should point to an array
  55593. of count + 1 integers. Upon return, the first element in the array will always contain
  55594. 0; the other elements will contain pixel positions on the screen for all of the
  55595. specified characters.
  55596.  
  55597. Note:  MeasureText only works with text displayed on the screen; since it
  55598.        doesn’t go through the QuickDraw procedure StdText, it can’t be used
  55599.        to measure text to be printed.
  55600.  
  55601. æKY GetFontInfo
  55602. æFc Quickdraw.h
  55603. æT Function
  55604. æTN A88B
  55605. æD pascal void GetFontInfo(FontInfo *info)
  55606.     = 0xA88B; 
  55607. æDT GetFontInfo((FontInfo *) info);
  55608. æMM
  55609. æRI I-173, P-83, 172
  55610. æC 
  55611. GetFontInfo returns the following information about the current grafPort’s character
  55612. font, taking into consideration the style and size in which the characters will be
  55613. drawn:  the ascent, descent, maximum character width (the greatest distance the pen
  55614. will move when a character is drawn), and leading
  55615. (the vertical distance between the descent line and the ascent line below it), all in
  55616. pixels. The FontInfo data type is defined as follows:
  55617.  
  55618. TYPE  FontInfo  =  RECORD
  55619.                      ascent:   INTEGER;    {ascent}
  55620.                      descent:  INTEGER;    {descent}
  55621.                      widMax:   INTEGER;    {maximum character width}
  55622.                      leading:  INTEGER     {leading}
  55623.                    END;
  55624.  
  55625. The line height (in pixels) can be determined by adding the ascent, descent, and
  55626. leading.
  55627.  
  55628. æKY ForeColor
  55629. æFc Quickdraw.h
  55630. æT Function
  55631. æTN A862
  55632. æD pascal void ForeColor(long color)
  55633.     = 0xA862; 
  55634. æDT ForeColor((long) color);
  55635. æMM
  55636. æRT 73
  55637. æRI I-173, N73-1
  55638. æC  
  55639. ForeColor sets the foreground color for all drawing in the current grafPort
  55640. (thePort^.fgColor) to the given color. The following standard colors are predefined: 
  55641. blackColor, whiteColor, redColor, greenColor, blueColor, cyanColor, magentaColor, and
  55642. yellowColor. The initial foreground color is blackColor.
  55643.  
  55644. æKY BackColor
  55645. æFc Quickdraw.h
  55646. æT Function
  55647. æTN A863
  55648. æD pascal void BackColor(long color)
  55649.     = 0xA863; 
  55650. æDT BackColor((long) color);
  55651. æMM
  55652. æRT 73
  55653. æRI I-174, N73-1
  55654. æC  
  55655. BackColor sets the background color for all drawing in the current grafPort
  55656. (thePort^.bkColor) to the given color. Eight standard colors are predefined
  55657. (see ForeColor above). The initial background color is whiteColor.
  55658.  
  55659. æKY ColorBit
  55660. æFc Quickdraw.h
  55661. æT Function
  55662. æTN A864
  55663. æD pascal void ColorBit(short whichBit)
  55664.     = 0xA864; 
  55665. æDT ColorBit((short) whichBit);
  55666. æRI I-174
  55667. æC  
  55668. ColorBit is called by printing software for a color printer, or other color-imaging
  55669. software, to set the current grafPort’s colrBit field to whichBit; this tells QuickDraw
  55670. which plane of the color picture to draw into. QuickDraw will draw into the plane
  55671. corresponding to bit number whichBit. Since QuickDraw can support output devices that
  55672. have up to 32 bits of color information per pixel, the possible range of values for
  55673. whichBit is 0 through 31. The initial value of the colrBit field is 0.
  55674.  
  55675. æKY SetRect
  55676. æFc Quickdraw.h
  55677. æT Function
  55678. æTN A8A7
  55679. æD pascal void SetRect(Rect *r,short left,short top,short right,short bottom)
  55680.     = 0xA8A7; 
  55681. æDT SetRect((Rect *) r,(short) left,(short) top,(short) right,(short) bottom);
  55682. æRI I-174
  55683. æC  
  55684. SetRect assigns the four boundary coordinates to the given rectangle. The result is a
  55685. rectangle with coordinates (left,top) (right,bottom).
  55686.  
  55687. This procedure is supplied as a utility to help you shorten your program text. If you
  55688. want a more readable text at the expense of length, you can assign integers (or
  55689. points) directly into the rectangle’s fields. There’s no significant code size or
  55690. execution speed advantage to either method.
  55691.  
  55692. æKY OffsetRect
  55693. æFc Quickdraw.h
  55694. æT Function
  55695. æTN A8A8
  55696. æD pascal void OffsetRect(Rect *r,short dh,short dv)
  55697.     = 0xA8A8; 
  55698. æDT OffsetRect((Rect *) r,(short) dh,(short) dv);
  55699. æRI I-174
  55700. æC  
  55701. OffsetRect moves the given rectangle by adding dh to each horizontal coordinate and
  55702. dv to each vertical coordinate. If dh and dv are positive, the movement is to the
  55703. right and down; if either is negative, the corresponding movement is in the opposite
  55704. direction. The rectangle retains its shape and size; it’s merely moved on the coordinate
  55705. plane. This doesn’t affect the screen unless you subsequently call a routine to draw
  55706. within the rectangle.
  55707.  
  55708. æKY InsetRect
  55709. æFc Quickdraw.h
  55710. æT Function
  55711. æTN A8A9
  55712. æD pascal void InsetRect(Rect *r,short dh,short dv)
  55713.     = 0xA8A9; 
  55714. æDT InsetRect((Rect *) r,(short) dh,(short) dv);
  55715. æRI I-175
  55716. æC  
  55717. InsetRect shrinks or expands the given rectangle. The left and right sides are moved
  55718. in by the amount specified by dh; the top and bottom are moved toward the center by
  55719. the amount specified by dv. If dh or dv is negative, the appropriate pair of sides is
  55720. moved outward instead of inward. The effect is to alter the size by 2*dh horizontally
  55721. and 2*dv vertically, with the rectangle remaining centered in the same place on the
  55722. coordinate plane.
  55723.  
  55724. If the resulting width or height becomes less than 1, the rectangle is set to the
  55725. empty rectangle (0,0)(0,0).
  55726.  
  55727. æKY SectRect
  55728. æFc Quickdraw.h
  55729. æT Function
  55730. æTN A8AA
  55731. æD pascal Boolean SectRect(const Rect *src1,const Rect *src2,Rect *dstRect)
  55732.     = 0xA8AA; 
  55733. æDT Boolean myVariable = SectRect((const Rect *) src1,(const Rect *) src2,(Rect *) dstRect);
  55734. æRI I-175
  55735. æC  
  55736. SectRect calculates the rectangle that’s the intersection of the two given rectangles,
  55737. and returns TRUE if they indeed intersect or FALSE if they don’t. Rectangles that
  55738. “touch” at a line or a point are not considered intersecting, because their intersection
  55739. rectangle (actually, in this case, an intersection line or point) doesn’t enclose any
  55740. bits in the bit image.
  55741.  
  55742. If the rectangles don’t intersect, the destination rectangle is set to (0,0)
  55743. (0,0). SectRect works correctly even if one of the source rectangles is also the
  55744. destination.
  55745.  
  55746. æKY UnionRect
  55747. æFc Quickdraw.h
  55748. æT Function
  55749. æTN A8AB
  55750. æD pascal void UnionRect(const Rect *src1,const Rect *src2,Rect *dstRect)
  55751.     = 0xA8AB; 
  55752. æDT UnionRect((const Rect *) src1,(const Rect *) src2,(Rect *) dstRect);
  55753. æRI I-175
  55754. æC  
  55755. UnionRect calculates the smallest rectangle that encloses both of the given rectangles.
  55756. It works correctly even if one of the source rectangles is also the destination.
  55757.  
  55758. æKY EqualRect
  55759. æFc Quickdraw.h
  55760. æT Function
  55761. æTN A8A6
  55762. æD pascal Boolean EqualRect(const Rect *rect1,const Rect *rect2)
  55763.     = 0xA8A6; 
  55764. æDT Boolean myVariable = EqualRect((const Rect *) rect1,(const Rect *) rect2);
  55765. æRI I-176
  55766. æC  
  55767. EqualRect compares the two given rectangles and returns TRUE if they’re equal or
  55768. FALSE if not. The two rectangles must have identical boundary coordinates to be
  55769. considered equal.
  55770.  
  55771. æKY EmptyRect
  55772. æFc Quickdraw.h
  55773. æT Function
  55774. æTN A8AE
  55775. æD pascal Boolean EmptyRect(const Rect *r)
  55776.     = 0xA8AE; 
  55777. æDT Boolean myVariable = EmptyRect((const Rect *) r);
  55778. æRI I-176
  55779. æC  
  55780. EmptyRect returns TRUE if the given rectangle is an empty rectangle or FALSE if not.
  55781. A rectangle is considered empty if the bottom coordinate is less than or equal to the
  55782. top or the right coordinate is less than or equal to the left.
  55783.  
  55784. æKY FrameRect
  55785. æFc Quickdraw.h
  55786. æT Function
  55787. æTN A8A1
  55788. æD pascal void FrameRect(const Rect *r)
  55789.     = 0xA8A1; 
  55790. æDT FrameRect((const Rect *) r);
  55791. æMM
  55792. æRI I-176
  55793. æC  
  55794. FrameRect draws an outline just inside the specified rectangle, using the current
  55795. grafPort’s pen pattern, mode, and size. The outline is as wide as the pen width and
  55796. as tall as the pen height. It’s drawn with the pnPat, according to the pattern transfer
  55797. mode specified by pnMode. The pen location is not changed by this procedure.
  55798.  
  55799. If a region is open and being formed, the outside outline of the new rectangle is
  55800. mathematically added to the region’s boundary.
  55801.  
  55802. æKY PaintRect
  55803. æFc Quickdraw.h
  55804. æT Function
  55805. æTN A8A2
  55806. æD pascal void PaintRect(const Rect *r)
  55807.     = 0xA8A2; 
  55808. æDT PaintRect((const Rect *) r);
  55809. æMM
  55810. æRI I-177, P-80, 178
  55811. æC  
  55812. PaintRect paints the specified rectangle with the current grafPort’s pen pattern and
  55813. mode. The rectangle is filled with the pnPat, according to the pattern transfer mode
  55814. specified by pnMode. The pen location is not changed by this procedure.
  55815.  
  55816. æKY EraseRect
  55817. æFc Quickdraw.h
  55818. æT Function
  55819. æTN A8A3
  55820. æD pascal void EraseRect(const Rect *r)
  55821.     = 0xA8A3; 
  55822. æDT EraseRect((const Rect *) r);
  55823. æMM
  55824. æRI I-177
  55825. æC  
  55826. EraseRect paints the specified rectangle with the current grafPort’s background
  55827. pattern bkPat (in patCopy mode). The grafPort’s pnPat and pnMode are ignored; the pen
  55828. location is not changed.
  55829.  
  55830. æKY InvertRect
  55831. æFc Quickdraw.h
  55832. æT Function
  55833. æTN A8A4
  55834. æD pascal void InvertRect(const Rect *r)
  55835.     = 0xA8A4; 
  55836. æDT InvertRect((const Rect *) r);
  55837. æMM
  55838. æRI I-177, P-80, 175
  55839. æC 
  55840. Assembly-language note:  The macro you invoke to call InvertRect from
  55841.                          assembly language is named _InverRect.
  55842.  
  55843. InvertRect inverts the pixels enclosed by the specified rectangle:  Every white pixel
  55844. becomes black and every black pixel becomes white. The grafPort’s pnPat, pnMode, and
  55845. bkPat are all ignored; the pen location is not changed.
  55846.  
  55847. æKY FillRect
  55848. æFc Quickdraw.h
  55849. æT Function
  55850. æTN A8A5
  55851. æD pascal void FillRect(const Rect *r,Pattern pat)
  55852.     = 0xA8A5; 
  55853. æDT FillRect((const Rect *) r,(Pattern) pat);
  55854. æMM
  55855. æRI I-177, P-80, 170
  55856. æC  
  55857. FillRect fills the specified rectangle with the given pattern (in patCopy mode). The
  55858. grafPort’s pnPat, pnMode, and bkPat are all ignored; the pen location is not changed.
  55859.  
  55860. æKY FrameOval
  55861. æFc Quickdraw.h
  55862. æT Function
  55863. æTN A8B7
  55864. æD pascal void FrameOval(const Rect *r)
  55865.     = 0xA8B7; 
  55866. æDT FrameOval((const Rect *) r);
  55867. æMM
  55868. æRI I-177
  55869. æC  
  55870. FrameOval draws an outline just inside the oval that fits inside the specified rectangle,
  55871. using the current grafPort’s pen pattern, mode, and size. The outline is as wide as
  55872. the pen width and as tall as the pen height. It’s drawn with the pnPat, according to
  55873. the pattern transfer mode specified by pnMode. The pen location is not changed by
  55874. this procedure.
  55875.  
  55876. If a region is open and being formed, the outside outline of the new oval is mathematically
  55877. added to the region’s boundary.
  55878.  
  55879. æKY PaintOval
  55880. æFc Quickdraw.h
  55881. æT Function
  55882. æTN A8B8
  55883. æD pascal void PaintOval(const Rect *r)
  55884.     = 0xA8B8; 
  55885. æDT PaintOval((const Rect *) r);
  55886. æMM
  55887. æRI I-178
  55888. æC  
  55889. PaintOval paints an oval just inside the specified rectangle with the current grafPort’s
  55890. pen pattern and mode. The oval is filled with the pnPat, according to the pattern
  55891. transfer mode specified by pnMode. The pen location is not changed by this procedure.
  55892.  
  55893. æKY EraseOval
  55894. æFc Quickdraw.h
  55895. æT Function
  55896. æTN A8B9
  55897. æD pascal void EraseOval(const Rect *r)
  55898.     = 0xA8B9; 
  55899. æDT EraseOval((const Rect *) r);
  55900. æMM
  55901. æRI I-178
  55902. æC  
  55903. EraseOval paints an oval just inside the specified rectangle with the current grafPort’s
  55904. background pattern bkPat (in patCopy mode). The grafPort’s pnPat and pnMode are
  55905. ignored; the pen location is not changed.
  55906.  
  55907. æKY InvertOval
  55908. æFc Quickdraw.h
  55909. æT Function
  55910. æTN A8BA
  55911. æD pascal void InvertOval(const Rect *r)
  55912.     = 0xA8BA; 
  55913. æDT InvertOval((const Rect *) r);
  55914. æMM
  55915. æRI I-178
  55916. æC  
  55917. InvertOval inverts the pixels enclosed by an oval just inside the specified rectangle:
  55918.  Every white pixel becomes black and every black pixel becomes white. The grafPort’s
  55919. pnPat, pnMode, and bkPat are all ignored; the pen location is not changed.
  55920.  
  55921. æKY FillOval
  55922. æFc Quickdraw.h
  55923. æT Function
  55924. æTN A8BB
  55925. æD pascal void FillOval(const Rect *r,Pattern pat)
  55926.     = 0xA8BB; 
  55927. æDT FillOval((const Rect *) r,(Pattern) pat);
  55928. æMM
  55929. æRI I-178
  55930. æC  
  55931. FillOval fills an oval just inside the specified rectangle with the given pattern (in
  55932. patCopy mode). The grafPort’s pnPat, pnMode, and bkPat are all ignored; the pen
  55933. location is not changed.
  55934.  
  55935. æKY FrameRoundRect
  55936. æFc Quickdraw.h
  55937. æT Function
  55938. æTN A8B0
  55939. æD pascal void FrameRoundRect(const Rect *r,short ovalWidth,short ovalHeight)
  55940.     = 0xA8B0; 
  55941. æDT FrameRoundRect((const Rect *) r,(short) ovalWidth,(short) ovalHeight);
  55942. æMM
  55943. æRI I-178
  55944. æC  
  55945. FrameRoundRect draws an outline just inside the specified rounded-corner rectangle,
  55946. using the current grafPort’s pen pattern, mode, and size. OvalWidth and ovalHeight
  55947. specify the diameters of curvature for the corners (see Figure 21). The outline is as
  55948. wide as the pen width and as tall as the pen height.
  55949. It’s drawn with the pnPat, according to the pattern transfer mode specified by pnMode.
  55950. The pen location is not changed by this procedure.
  55951.  
  55952. •••Refer to Figure 21.•••
  55953.  
  55954. Figure 21–Rounded-Corner Rectangle
  55955.  
  55956. If a region is open and being formed, the outside outline of the new rounded-corner
  55957. rectangle is mathematically added to the region’s boundary.
  55958.  
  55959. æKY PaintRoundRect
  55960. æFc Quickdraw.h
  55961. æT Function
  55962. æTN A8B1
  55963. æD pascal void PaintRoundRect(const Rect *r,short ovalWidth,short ovalHeight)
  55964.     = 0xA8B1; 
  55965. æDT PaintRoundRect((const Rect *) r,(short) ovalWidth,(short) ovalHeight);
  55966. æMM
  55967. æRI I-179
  55968. æC  
  55969. PaintRoundRect paints the specified rounded-corner rectangle with the current grafPort’s
  55970. pen pattern and mode. OvalWidth and ovalHeight specify the diameters of curvature for
  55971. the corners.
  55972.  
  55973. The rounded-corner rectangle is filled with the pnPat, according to the pattern
  55974. transfer mode specified by pnMode. The pen location is not changed by this procedure.
  55975.  
  55976. æKY EraseRoundRect
  55977. æFc Quickdraw.h
  55978. æT Function
  55979. æTN A8B2
  55980. æD pascal void EraseRoundRect(const Rect *r,short ovalWidth,short ovalHeight)
  55981.     = 0xA8B2; 
  55982. æDT EraseRoundRect((const Rect *) r,(short) ovalWidth,(short) ovalHeight);
  55983. æMM
  55984. æRI I-179
  55985. æC  
  55986. EraseRoundRect paints the specified rounded-corner rectangle with the current grafPort’s
  55987. background pattern bkPat (in patCopy mode).
  55988.  
  55989. OvalWidth and ovalHeight specify the diameters of curvature for the corners. The
  55990. grafPort’s pnPat and pnMode are ignored; the pen location is not changed.
  55991.  
  55992. æKY InvertRoundRect
  55993. æFc Quickdraw.h
  55994. æT Function
  55995. æTN A8B3
  55996. æD pascal void InvertRoundRect(const Rect *r,short ovalWidth,short ovalHeight)
  55997.     = 0xA8B3; 
  55998. æDT InvertRoundRect((const Rect *) r,(short) ovalWidth,(short) ovalHeight);
  55999. æMM
  56000. æRI I-179
  56001. æC  
  56002. Assembly-language note:  The macro you invoke to call InvertRoundRect from
  56003.                          assembly language is named _InverRoundRect.
  56004.  
  56005. InvertRoundRect inverts the pixels enclosed by the specified rounded-corner rectangle:
  56006.  Every white pixel becomes black and every black pixel becomes white. OvalWidth and
  56007. ovalHeight specify the diameters of curvature for the corners. The grafPort’s pnPat,
  56008. pnMode, and bkPat are all ignored; the pen location is not changed.
  56009.  
  56010. æKY FillRoundRect
  56011. æFc Quickdraw.h
  56012. æT Function
  56013. æTN A8B4
  56014. æD pascal void FillRoundRect(const Rect *r,short ovalWidth,short ovalHeight,
  56015.     Pattern pat)
  56016.     = 0xA8B4; 
  56017. æDT FillRoundRect((const Rect *) r,(short) ovalWidth,(short) ovalHeight,()
  56018.     Pattern pat);
  56019. æMM
  56020. æRI I-179
  56021. æC  
  56022. FillRoundRect fills the specified rounded-corner rectangle with the given pattern (in
  56023. patCopy mode). OvalWidth and ovalHeight specify the diameters of curvature for the
  56024. corners. The grafPort’s pnPat, pnMode, and bkPat are all ignored; the pen location is
  56025. not changed.
  56026.  
  56027. æKY FrameArc
  56028. æFc Quickdraw.h
  56029. æT Function
  56030. æTN A8BE
  56031. æD pascal void FrameArc(const Rect *r,short startAngle,short arcAngle)
  56032.     = 0xA8BE; 
  56033. æDT FrameArc((const Rect *) r,(short) startAngle,(short) arcAngle);
  56034. æMM
  56035. æRI I-180
  56036. æC  
  56037. FrameArc draws an arc of the oval that fits inside the specified rectangle, using the
  56038. current grafPort’s pen pattern, mode, and size. StartAngle indicates where the arc
  56039. begins and is treated MOD 360. ArcAngle defines the extent of the arc. The angles are
  56040. given in positive or negative degrees; a positive angle goes clockwise, while a
  56041. negative angle goes counterclockwise. Zero degrees is at 12 o’clock high, 90 (or
  56042. –270) is at 3 o’clock, 180 (or –180) is at 6 o’clock, and 270 (or –90) is at 9 o’clock.
  56043. Other angles are measured relative to the enclosing rectangle:  A line from the
  56044. center of the rectangle through its top right corner is at 45 degrees, even if the
  56045. rectangle isn’t square; a line through the bottom right corner is at 135 degrees, and
  56046. so on (see Figure 22).
  56047.  
  56048. •••Refer to Figure 22.•••
  56049.  
  56050. Figure 22–Operations on Arcs and Wedges
  56051.  
  56052. The arc is as wide as the pen width and as tall as the pen height. It’s drawn with
  56053. the pnPat, according to the pattern transfer mode specified by pnMode. The pen location
  56054. is not changed by this procedure.
  56055.  
  56056. Warning:  FrameArc differs from other QuickDraw routines that frame shapes
  56057.           in that the arc is not mathematically added to the boundary of a
  56058.           region that’s open and being formed.
  56059.  
  56060. Note:  QuickDraw doesn’t provide a routine for drawing an outlined wedge
  56061.        of an oval.
  56062.  
  56063. æKY PaintArc
  56064. æFc Quickdraw.h
  56065. æT Function
  56066. æTN A8BF
  56067. æD pascal void PaintArc(const Rect *r,short startAngle,short arcAngle)
  56068.     = 0xA8BF; 
  56069. æDT PaintArc((const Rect *) r,(short) startAngle,(short) arcAngle);
  56070. æMM
  56071. æRI I-180
  56072. æC  
  56073. PaintArc paints a wedge of the oval just inside the specified rectangle with the
  56074. current grafPort’s pen pattern and mode. StartAngle and arcAngle define the arc of
  56075. the wedge as in FrameArc. The wedge is filled with the pnPat, according to the pattern
  56076. transfer mode specified by pnMode. The pen location is not changed by this procedure.
  56077.  
  56078. æKY EraseArc
  56079. æFc Quickdraw.h
  56080. æT Function
  56081. æTN A8C0
  56082. æD pascal void EraseArc(const Rect *r,short startAngle,short arcAngle)
  56083.     = 0xA8C0; 
  56084. æDT EraseArc((const Rect *) r,(short) startAngle,(short) arcAngle);
  56085. æMM
  56086. æRI I-180
  56087. æC  
  56088. EraseArc paints a wedge of the oval just inside the specified rectangle with the
  56089. current grafPort’s background pattern bkPat (in patCopy mode). StartAngle and arcAngle
  56090. define the arc of the wedge as in FrameArc. The grafPort’s pnPat and pnMode are
  56091. ignored; the pen location is not changed.
  56092.  
  56093. æKY InvertArc
  56094. æFc Quickdraw.h
  56095. æT Function
  56096. æTN A8C1
  56097. æD pascal void InvertArc(const Rect *r,short startAngle,short arcAngle)
  56098.     = 0xA8C1; 
  56099. æDT InvertArc((const Rect *) r,(short) startAngle,(short) arcAngle);
  56100. æMM
  56101. æRI I-181
  56102. æC  
  56103. InvertArc inverts the pixels enclosed by a wedge of the oval just inside the specified
  56104. rectangle:  Every white pixel becomes black and every black pixel becomes white.
  56105. StartAngle and arcAngle define the arc of the wedge as in FrameArc. The grafPort’s
  56106. pnPat, pnMode, and bkPat are all ignored; the pen location is not changed.
  56107.  
  56108. æKY FillArc
  56109. æFc Quickdraw.h
  56110. æT Function
  56111. æTN A8C2
  56112. æD pascal void FillArc(const Rect *r,short startAngle,short arcAngle,Pattern pat)
  56113.     = 0xA8C2; 
  56114. æDT FillArc((const Rect *) r,(short) startAngle,(short) arcAngle,(Pattern) pat);
  56115. æMM
  56116. æRI I-181
  56117. æC  
  56118. FillArc fills a wedge of the oval just inside the specified rectangle with the given
  56119. pattern (in patCopy mode). StartAngle and arcAngle define the arc of the wedge as in
  56120. FrameArc. The grafPort’s pnPat, pnMode, and bkPat are all ignored; the pen location
  56121. is not changed.
  56122.  
  56123. æKY NewRgn
  56124. æFc Quickdraw.h
  56125. æT Function
  56126. æTN A8D8
  56127. æD pascal RgnHandle NewRgn(void)
  56128.     = 0xA8D8; 
  56129. æDT RgnHandle myVariable = NewRgn()(void);
  56130. æMM
  56131. æRT 193
  56132. æRI I-181, P-85, 177
  56133. æC  
  56134. NewRgn allocates space for a new, variable-size region, initializes it to the empty
  56135. region defined by the rectangle (0,0)(0,0), and returns a handle to the new region.
  56136.  
  56137. Warning:  Only this function creates new regions; all other routines just
  56138.           alter the size and shape of existing regions. Before a region’s
  56139.           handle can be passed to any drawing or calculation routine, space
  56140.           must already have been allocated for the region.
  56141.  
  56142. æKY OpenRgn
  56143. æFc Quickdraw.h
  56144. æT Function
  56145. æTN A8DA
  56146. æD pascal void OpenRgn(void)
  56147.     = 0xA8DA; 
  56148. æDT OpenRgn()(void);
  56149. æMM
  56150. æRI I-181, P-85, 178
  56151. æC  
  56152. OpenRgn tells QuickDraw to allocate temporary space and start saving lines and framed
  56153. shapes for later processing as a region definition. While a region is open, all calls
  56154. to Line, LineTo, and the procedures that draw framed shapes
  56155. (except arcs) affect the outline of the region. Only the line endpoints and shape
  56156. boundaries affect the region definition; the pen mode, pattern, and size do not
  56157. affect it. In fact, OpenRgn calls HidePen, so no drawing occurs on the screen while
  56158. the region is open (unless you called ShowPen just after OpenRgn, or you called
  56159. ShowPen previously without balancing it by a call to HidePen). Since the pen hangs
  56160. below and to the right of the pen location, drawing lines with even the smallest pen
  56161. will change bits that lie outside the region you define.
  56162.  
  56163. The outline of a region is mathematically defined and infinitely thin, and separates
  56164. the bit image into two groups of bits:  Those within the region and those outside it.
  56165. A region should consist of one or more closed loops. Each framed shape itself constitutes
  56166. a loop. Any lines drawn with Line or LineTo should connect with each other or with a
  56167. framed shape. Even though the on-screen presentation of a region is clipped, the
  56168. definition of a region is not; you can define a region anywhere on the coordinate
  56169. plane with complete disregard for the location of various grafPort entities on that
  56170. plane.
  56171.  
  56172. When a region is open, the current grafPort’s rgnSave field contains a handle to
  56173. information related to the region definition. If you want to temporarily disable the
  56174. collection of lines and shapes, you can save the current value of this field, set the
  56175. field to NIL, and later restore the saved value to resume the region definition.
  56176. Also, calling SetPort while a region is being formed will discontinue formation of
  56177. the region until another call to SetPort resets the region’s original grafPort.
  56178.  
  56179. Warning:  Do not call OpenRgn while another region or polygon is already
  56180.           open. All open regions but the most recent will behave strangely.
  56181.  
  56182. Note:  Regions are limited to 32K bytes.
  56183.  
  56184. æKY CloseRgn
  56185. æFc Quickdraw.h
  56186. æT Function
  56187. æTN A8DB
  56188. æD pascal void CloseRgn(RgnHandle dstRgn)
  56189.     = 0xA8DB; 
  56190. æDT CloseRgn((RgnHandle) dstRgn);
  56191. æMM
  56192. æRI I-182, P-85, 167
  56193. æC  
  56194. CloseRgn stops the collection of lines and framed shapes, organizes them into a
  56195. region definition, and saves the resulting region in the region indicated by dstRgn.
  56196. CloseRgn does not create the destination region; space must already have been allocated
  56197. for it. You should perform one and only one CloseRgn for every OpenRgn. CloseRgn
  56198. calls ShowPen, balancing the HidePen call made by OpenRgn.
  56199.  
  56200. Here’s an example of how to create and open a region, define a barbell shape, close
  56201. the region, draw it, and dispose of it:
  56202.  
  56203.   barbell := NewRgn;                    {create a new region}
  56204.   OpenRgn;                              {begin collecting stuff}
  56205.       SetRect(tempRect,20,20,30,50);    {form the left weight}
  56206.       FrameOval(tempRect);
  56207.       SetRect(tempRect,25,30,85,40);    {form the bar}
  56208.       FrameRect(tempRect);
  56209.       SetRect(tempRect,80,20,90,50);    {form the right weight}
  56210.       FrameOval(tempRect);
  56211.   CloseRgn(barbell);                    {we're done; save in barbell}
  56212.   FillRgn(barbell,black);               {draw it on the screen}
  56213.   DisposeRgn(barbell)                   {dispose of the region}
  56214.  
  56215. æKY BitMapToRegion
  56216. æFc Quickdraw.h
  56217. æT Function
  56218. æTN A8D7
  56219. æD pascal OSErr BitMapToRegion(RgnHandle region,const BitMap *bMap)
  56220.     = 0xA8D7; 
  56221. æDT OSErr myVariable = BitMapToRegion((RgnHandle) region,(const BitMap *) bMap);
  56222. æC 
  56223. The region parameter must be a valid region handle created with a NewRgn
  56224. function. The old region contents are lost.
  56225.  
  56226. The bMap parameter may either be a BitMap or PixMap record. If a PixMap record
  56227. is passed, its pixel size (bits per pixel) must be 1. 
  56228.  
  56229. Result codes
  56230.     rgnTooBigErr   -500  BitMap would convert into a region greater 
  56231.                          than 32 KB 
  56232. pixmapTooDeepErr   -148  PixMap record is deeper than 1 bit per pixel
  56233.  
  56234. æKY DisposeRgn
  56235. æFc Quickdraw.h
  56236. æT Function
  56237. æTN A8D9
  56238. æD pascal void DisposeRgn(RgnHandle rgn)
  56239.     = 0xA8D9; 
  56240. æDT DisposeRgn((RgnHandle) rgn);
  56241. æMM
  56242. æRI I-182
  56243. æC  
  56244. Assembly-language note:  The macro you invoke to call DisposeRgn from
  56245.                          assembly language is named _DisposRgn.
  56246.  
  56247. DisposeRgn releases the memory occupied by the given region. Use this only after
  56248. you’re completely through with a temporary region.
  56249.  
  56250. æKY CopyRgn
  56251. æFc Quickdraw.h
  56252. æT Function
  56253. æTN A8DC
  56254. æD pascal void CopyRgn(RgnHandle srcRgn,RgnHandle dstRgn)
  56255.     = 0xA8DC; 
  56256. æDT CopyRgn((RgnHandle) srcRgn,(RgnHandle) dstRgn);
  56257. æMM
  56258. æRI I-183
  56259. æC  
  56260. CopyRgn copies the mathematical structure of srcRgn into dstRgn; that is, it makes a
  56261. duplicate copy of srcRgn. Once this is done, srcRgn may be altered (or even disposed
  56262. of) without affecting dstRgn. CopyRgn does not create the destination region; space
  56263. must already have been allocated for it.
  56264.  
  56265. æKY SetEmptyRgn
  56266. æFc Quickdraw.h
  56267. æT Function
  56268. æTN A8DD
  56269. æD pascal void SetEmptyRgn(RgnHandle rgn)
  56270.     = 0xA8DD; 
  56271. æDT SetEmptyRgn((RgnHandle) rgn);
  56272. æMM
  56273. æRI I-183
  56274. æC  
  56275. SetEmptyRgn destroys the previous structure of the given region, then sets the new
  56276. structure to the empty region defined by the rectangle (0,0)(0,0).
  56277.  
  56278. æKY SetRectRgn
  56279. æFc Quickdraw.h
  56280. æT Function
  56281. æTN A8DE
  56282. æD pascal void SetRectRgn(RgnHandle rgn,short left,short top,short right,short bottom)
  56283.     = 0xA8DE; 
  56284. æDT SetRectRgn((RgnHandle) rgn,(short) left,(short) top,(short) right,(short) bottom);
  56285. æMM
  56286. æRI I-183
  56287. æC  
  56288. Assembly-language note:  The macro you invoke to call SetRectRgn from
  56289.                          assembly language is named _SetRecRgn.
  56290.  
  56291. SetRectRgn destroys the previous structure of the given region, and then sets the new
  56292. structure to the rectangle specified by left, top, right, and bottom.
  56293.  
  56294. If the specified rectangle is empty (that is, right<=left or bottom<=top), the region
  56295. is set to the empty region defined by the rectangle (0,0)(0,0).
  56296.  
  56297. æKY RectRgn
  56298. æFc Quickdraw.h
  56299. æT Function
  56300. æTN A8DF
  56301. æD pascal void RectRgn(RgnHandle rgn,const Rect *r)
  56302.     = 0xA8DF; 
  56303. æDT RectRgn((RgnHandle) rgn,(const Rect *) r);
  56304. æMM
  56305. æRI I-183
  56306. æC  
  56307. RectRgn destroys the previous structure of the given region, and then sets the new
  56308. structure to the rectangle specified by r. This is the same as SetRectRgn, except the
  56309. given rectangle is defined by a rectangle rather than by four boundary coordinates.
  56310.  
  56311. æKY OffsetRgn
  56312. æFc Quickdraw.h
  56313. æT Function
  56314. æTN A8E0
  56315. æD pascal void OffsetRgn(RgnHandle rgn,short dh,short dv)
  56316.     = 0xA8E0; 
  56317. æDT OffsetRgn((RgnHandle) rgn,(short) dh,(short) dv);
  56318. æRI I-183
  56319. æC  
  56320. Assembly-language note:  The macro you invoke to call OffsetRgn from
  56321.                          assembly language is named _OfsetRgn.
  56322.  
  56323. OffsetRgn moves the region on the coordinate plane, a distance of dh horizontally and
  56324. dv vertically. This doesn’t affect the screen unless you subsequently call a routine
  56325. to draw the region. If dh and dv are positive, the movement is to the right and down;
  56326. if either is negative, the corresponding movement is in the opposite direction. The
  56327. region retains its size and shape.
  56328.  
  56329. Note:  OffsetRgn is an especially efficient operation, because most of
  56330.        the data defining a region is stored relative to rgnBBox and so
  56331.  
  56332. æKY InsetRgn
  56333. æFc Quickdraw.h
  56334. æT Function
  56335. æTN A8E1
  56336. æD pascal void InsetRgn(RgnHandle rgn,short dh,short dv)
  56337.     = 0xA8E1; 
  56338. æDT InsetRgn((RgnHandle) rgn,(short) dh,(short) dv);
  56339. æMM
  56340. æRI I-184
  56341. æC  
  56342. InsetRgn shrinks or expands the region. All points on the region boundary are moved
  56343. inwards a distance of dv vertically and dh horizontally; if dh or dv is negative, the
  56344. points are moved outwards in that direction. InsetRgn leaves the region “centered” at
  56345. the same position, but moves the outline in (for positive values of dh and dv) or out
  56346. (for negative values of dh and dv). InsetRgn of a rectangular region works just like
  56347. InsetRect.
  56348.  
  56349. Note:  InsetRgn temporarily uses heap space that’s twice the size of
  56350.        the original region.
  56351.  
  56352. æKY SectRgn
  56353. æFc Quickdraw.h
  56354. æT Function
  56355. æTN A8E4
  56356. æD pascal void SectRgn(RgnHandle srcRgnA,RgnHandle srcRgnB,RgnHandle dstRgn)
  56357.     = 0xA8E4; 
  56358. æDT SectRgn((RgnHandle) srcRgnA,(RgnHandle) srcRgnB,(RgnHandle) dstRgn);
  56359. æMM
  56360. æRI I-184
  56361. æC  
  56362. SectRgn calculates the intersection of two regions and places the intersection in a
  56363. third region. This does not create the destination region; space must already have
  56364. been allocated for it. The destination region can be one of the source regions, if
  56365. desired.
  56366.  
  56367. If the regions do not intersect, or one of the regions is empty, the destination is
  56368. set to the empty region defined by the rectangle (0,0)(0,0).
  56369.  
  56370. Note:  SectRgn may temporarily use heap space that’s twice the size of
  56371.        the two input regions.
  56372.  
  56373. æKY UnionRgn
  56374. æFc Quickdraw.h
  56375. æT Function
  56376. æTN A8E5
  56377. æD pascal void UnionRgn(RgnHandle srcRgnA,RgnHandle srcRgnB,RgnHandle dstRgn)
  56378.     = 0xA8E5; 
  56379. æDT UnionRgn((RgnHandle) srcRgnA,(RgnHandle) srcRgnB,(RgnHandle) dstRgn);
  56380. æMM
  56381. æRI I-184
  56382. æC 
  56383. UnionRgn calculates the union of two regions and places the union in a third region.
  56384. This does not create the destination region; space must already have been allocated
  56385. for it. The destination region can be one of the source regions, if desired.
  56386.  
  56387. If both regions are empty, the destination is set to the empty region defined by the
  56388. rectangle (0,0)(0,0).
  56389.  
  56390. Note:  UnionRgn may temporarily use heap space that’s twice the size of
  56391.        the two input regions.
  56392.  
  56393. æKY DiffRgn
  56394. æFc Quickdraw.h
  56395. æT Function
  56396. æTN A8E6
  56397. æD pascal void DiffRgn(RgnHandle srcRgnA,RgnHandle srcRgnB,RgnHandle dstRgn)
  56398.     = 0xA8E6; 
  56399. æDT DiffRgn((RgnHandle) srcRgnA,(RgnHandle) srcRgnB,(RgnHandle) dstRgn);
  56400. æMM
  56401. æRI I-184
  56402. æC  
  56403. DiffRgn subtracts srcRgnB from srcRgnA and places the difference in a third region.
  56404. This does not create the destination region; space must already have been allocated
  56405. for it. The destination region can be one of the source regions, if desired.
  56406.  
  56407. If the first source region is empty, the destination is set to the empty region
  56408. defined by the rectangle (0,0)(0,0).
  56409.  
  56410. Note:  DiffRgn may temporarily use heap space that’s twice the size of
  56411.        the two input regions.
  56412.  
  56413. æKY XorRgn
  56414. æFc Quickdraw.h
  56415. æT Function
  56416. æTN A8E7
  56417. æD pascal void XorRgn(RgnHandle srcRgnA,RgnHandle srcRgnB,RgnHandle dstRgn)
  56418.     = 0xA8E7; 
  56419. æDT XorRgn((RgnHandle) srcRgnA,(RgnHandle) srcRgnB,(RgnHandle) dstRgn);
  56420. æMM
  56421. æRI I-185
  56422. æC  
  56423. XorRgn calculates the difference between the union and the intersection of srcRgnA
  56424. and srcRgnB and places the result in dstRgn. This does not create the destination
  56425. region; space must already have been allocated for it. The destination region can be
  56426. one of the source regions, if desired.
  56427.  
  56428. If the regions are coincident, the destination is set to the empty region defined by
  56429. the rectangle (0,0)(0,0).
  56430.  
  56431. Note:  XorRgn may temporarily use heap space that’s twice the size of
  56432.        the two input regions.
  56433.  
  56434. æKY RectInRgn
  56435. æFc Quickdraw.h
  56436. æT Function
  56437. æTN A8E9
  56438. æD pascal Boolean RectInRgn(const Rect *r,RgnHandle rgn)
  56439.     = 0xA8E9; 
  56440. æDT Boolean myVariable = RectInRgn((const Rect *) r,(RgnHandle) rgn);
  56441. æRI I-185
  56442. æC  
  56443. RectInRgn checks whether the given rectangle intersects the specified region, and
  56444. returns TRUE if the intersection encloses at least one bit or FALSE if not.
  56445.  
  56446. Note:  RectInRgn will sometimes return TRUE when the rectangle merely
  56447.        intersects the region’s enclosing rectangle. If you need to know
  56448.        exactly whether a given rectangle intersects the actual region,
  56449.        you can use RectRgn to set the rectangle to a region, and call
  56450.        SectRgn to see whether the two regions intersect:  If the result
  56451.        of SectRgn is an empty region, then the rectangle doesn’t intersect
  56452.        the region.
  56453.  
  56454. æKY EqualRgn
  56455. æFc Quickdraw.h
  56456. æT Function
  56457. æTN A8E3
  56458. æD pascal Boolean EqualRgn(RgnHandle rgnA,RgnHandle rgnB)
  56459.     = 0xA8E3; 
  56460. æDT Boolean myVariable = EqualRgn((RgnHandle) rgnA,(RgnHandle) rgnB);
  56461. æRI I-185
  56462. æC 
  56463. EqualRgn compares the two given regions and returns TRUE if they’re equal or FALSE if
  56464. not. The two regions must have identical sizes, shapes, and locations to be considered
  56465. equal. Any two empty regions are always equal.
  56466.  
  56467. æKY EmptyRgn
  56468. æFc Quickdraw.h
  56469. æT Function
  56470. æTN A8E2
  56471. æD pascal Boolean EmptyRgn(RgnHandle rgn)
  56472.     = 0xA8E2; 
  56473. æDT Boolean myVariable = EmptyRgn((RgnHandle) rgn);
  56474. æRI I-186
  56475. æC  
  56476. EmptyRgn returns TRUE if the region is an empty region or FALSE if not. Some of the
  56477. circumstances in which an empty region can be created are:  a NewRgn call; a CopyRgn
  56478. of an empty region; a SetRectRgn or RectRgn with an empty rectangle as an argument;
  56479. CloseRgn without a previous OpenRgn or with no drawing after an OpenRgn; OffsetRgn of
  56480. an empty region; InsetRgn with an empty region or too large an inset; SectRgn of
  56481. nonintersecting regions; UnionRgn of two empty regions; and DiffRgn or XorRgn of two
  56482. identical or nonintersecting regions.
  56483.  
  56484. æKY FrameRgn
  56485. æFc Quickdraw.h
  56486. æT Function
  56487. æTN A8D2
  56488. æD pascal void FrameRgn(RgnHandle rgn)
  56489.     = 0xA8D2; 
  56490. æDT FrameRgn((RgnHandle) rgn);
  56491. æMM
  56492. æRI I-186
  56493. æC  
  56494. FrameRgn draws an outline just inside the specified region, using the current grafPort’s
  56495. pen pattern, mode, and size. The outline is as wide as the pen width and as tall as
  56496. the pen height. It’s drawn with the pnPat, according to the pattern transfer mode
  56497. specified by pnMode. The outline will never go outside the region boundary. The pen
  56498. location is not changed by this procedure.
  56499.  
  56500. If a region is open and being formed, the outside outline of the region being framed
  56501. is mathematically added to that region’s boundary.
  56502.  
  56503. Note:  FrameRgn actually does a CopyRgn, an InsetRgn, and a DiffRgn;
  56504.        it may temporarily use heap space that’s three times the size
  56505.        of the original region.
  56506.  
  56507. æKY PaintRgn
  56508. æFc Quickdraw.h
  56509. æT Function
  56510. æTN A8D3
  56511. æD pascal void PaintRgn(RgnHandle rgn)
  56512.     = 0xA8D3; 
  56513. æDT PaintRgn((RgnHandle) rgn);
  56514. æMM
  56515. æRI I-186
  56516. æC  
  56517. PaintRgn paints the specified region with the current grafPort’s pen pattern and pen
  56518. mode. The region is filled with the pnPat, according to the pattern transfer mode
  56519. specified by pnMode. The pen location is not changed by this procedure.
  56520.  
  56521. æKY EraseRgn
  56522. æFc Quickdraw.h
  56523. æT Function
  56524. æTN A8D4
  56525. æD pascal void EraseRgn(RgnHandle rgn)
  56526.     = 0xA8D4; 
  56527. æDT EraseRgn((RgnHandle) rgn);
  56528. æMM
  56529. æRI I-186
  56530. æC  
  56531. EraseRgn paints the specified region with the current grafPort’s background pattern
  56532. bkPat (in patCopy mode). The grafPort’s pnPat and pnMode are ignored; the pen location
  56533. is not changed.
  56534.  
  56535. æKY InvertRgn
  56536. æFc Quickdraw.h
  56537. æT Function
  56538. æTN A8D5
  56539. æD pascal void InvertRgn(RgnHandle rgn)
  56540.     = 0xA8D5; 
  56541. æDT InvertRgn((RgnHandle) rgn);
  56542. æMM
  56543. æRI I-186
  56544. æC  
  56545. Assembly-language note:  The macro you invoke to call InvertRgn from
  56546.                          assembly language is named _InverRgn.
  56547.  
  56548. InvertRgn inverts the pixels enclosed by the specified region:  Every white pixel
  56549. becomes black and every black pixel becomes white. The grafPort’s pnPat, pnMode, and
  56550. bkPat are all ignored; the pen location is not changed.
  56551.  
  56552. æKY FillRgn
  56553. æFc Quickdraw.h
  56554. æT Function
  56555. æTN A8D6
  56556. æD pascal void FillRgn(RgnHandle rgn,Pattern pat)
  56557.     = 0xA8D6; 
  56558. æDT FillRgn((RgnHandle) rgn,(Pattern) pat);
  56559. æMM
  56560. æRI I-187
  56561. æC  
  56562. FillRgn fills the specified region with the given pattern (in patCopy mode). The
  56563. grafPort’s pnPat, pnMode, and bkPat are all ignored; the pen location is not changed.
  56564.  
  56565. æKY ScrollRect
  56566. æFc Quickdraw.h
  56567. æT Function
  56568. æTN A8EF
  56569. æD pascal void ScrollRect(const Rect *r,short dh,short dv,RgnHandle updateRgn)
  56570.     = 0xA8EF; 
  56571. æDT ScrollRect((const Rect *) r,(short) dh,(short) dv,(RgnHandle) updateRgn);
  56572. æMM
  56573. æRI I-187
  56574. æC  
  56575. ScrollRect shifts (“scrolls”) the bits that are inside the intersection of the specified
  56576. rectangle and the visRgn, clipRgn, portRect, and portBits.bounds of the current
  56577. grafPort. No other bits are affected. The bits are shifted a distance of dh horizontally
  56578. and dv vertically. The positive directions are
  56579. to the right and down. Bits that are shifted out of the scroll area are
  56580. lost—they’re neither placed outside the area nor saved. The space created by the
  56581. scroll is filled with the grafPort’s background pattern (thePort^.bkPat), and the
  56582. updateRgn is changed to this filled area (see Figure 23).
  56583.  
  56584. •••Refer to Figure 23.•••
  56585.  
  56586. Figure 23–Scrolling
  56587.  
  56588. ScrollRect doesn’t change the coordinate system of the grafPort, it simply moves the
  56589. entire document to different coordinates. Notice that ScrollRect doesn’t move the pen
  56590. and the clipRgn. However, since the document has moved, they’re in a different position
  56591. relative to the document.
  56592.  
  56593. To restore the coordinates of the document to what they were before the ScrollRect,
  56594. you can use the SetOrigin procedure. In Figure 23, suppose that before the ScrollRect
  56595. the top left corner of the document was at coordinates
  56596. (100,100). After ScrollRect(r,10,20...), the coordinates of the document are offset
  56597. by the specified values. You could call SetOrigin(90,80) to offset the coordinate
  56598. system to compensate for the scroll (see Figure 14 in the
  56599. “Coordinates in GrafPorts” section for an illustration). The document itself doesn’t
  56600. move as a result of SetOrigin, but the pen and clipRgn move down and to the right,
  56601. and are restored to their original position relative to the document. Notice that
  56602. updateRgn will still need to be redrawn.
  56603.  
  56604. æKY CopyBits
  56605. æFc Quickdraw.h
  56606. æT Function
  56607. æTN A8EC
  56608. æD pascal void CopyBits(const BitMap *srcBits,const BitMap *dstBits,const Rect *srcRect,
  56609.     const Rect *dstRect,short mode,RgnHandle maskRgn)
  56610.     = 0xA8EC; 
  56611. æDT CopyBits((const BitMap *) srcBits,(const BitMap *) dstBits,(const Rect *) srcRect,(
  56612.     const Rect) * dstRect,(short) mode,(RgnHandle) maskRgn);
  56613. æMM
  56614. æRT 41, 55, 163
  56615. æRI I-188, V-70, N41-1, 2, N55, N120, N163
  56616. æC  
  56617. CopyBits transfers a bit image between any two bit maps and clips the result to the
  56618. area specified by the maskRgn parameter. The transfer may be performed in any of the
  56619. eight source transfer modes. The result is always clipped to the maskRgn and the
  56620. boundary rectangle of the destination bit map; if the destination bit map is the
  56621. current grafPort’s portBits, it’s also clipped to the intersection of the grafPort’s
  56622. clipRgn and visRgn. If you don’t want to clip to a maskRgn, just pass NIL for the
  56623. maskRgn parameter. The dstRect and maskRgn coordinates are in terms of the dstBits.bounds
  56624. coordinate system, and the srcRect coordinates are in terms of the srcBits.bounds
  56625. coordinates.
  56626.  
  56627. Warning:  If you perform a CopyBits between two grafPorts that overlap,
  56628.           you must first convert to global coordinates, and then specify
  56629.           screenBits for both srcBits and dstBits.
  56630.  
  56631. The bits enclosed by the source rectangle are transferred into the destination rectangle
  56632. according to the rules of the chosen mode. The source transfer modes are as follows:
  56633.  
  56634.   srcCopy    notSrcCopy
  56635.   srcOr      notSrcXor
  56636.   srcXor     notSrcOr
  56637.   srcBic     notSrcBic
  56638.  
  56639. The source rectangle is completely aligned with the destination rectangle; if the
  56640. rectangles are of different sizes, the bit image is expanded or shrunk as necessary
  56641. to fit the destination rectangle. For example, if the bit image is a circle in a
  56642. square source rectangle, and the destination rectangle is not square, the bit image
  56643. appears as an oval in the destination (see Figure 24).
  56644.  
  56645. •••Refer to Figure 24.•••
  56646.  
  56647. Figure 24–Operation of CopyBits
  56648.  
  56649. CopyBits now accepts either bitMaps or pixMaps as parameters. For convenience, just
  56650. as you could pass the current port^.portBits as a parameter to CopyBits, you can now
  56651. pass GrafPtr(cPort)^.portBits. (Recall that in a cGrafPort the high two bits of the
  56652. portVersion field are set. This field, in the same position in the port as portBits.rowBytes,
  56653. indicates to QuickDraw that it has been passed a portPixMap handle.)
  56654.  
  56655. This call transfers an image from one bitMap or pixMap to another bitMap or pixMap.
  56656. The source and destination may be of different depths, of different sizes, and they
  56657. may have different color tables. Note, however, that the destination pixMap is assumed
  56658. to use the same color table as the gDevice.
  56659. (This is because an inverse table is required for translation to the destination’s
  56660. color table.)
  56661.  
  56662. During a CopyBits call, the foreground and background colors are applied to the
  56663. image. To avoid unwanted coloring of the image, set the foreground to black and the
  56664. background to white before calling this routine.
  56665.  
  56666. æKY SeedFill
  56667. æFc Quickdraw.h
  56668. æT Function
  56669. æTN A839
  56670. æD pascal void SeedFill(Ptr srcPtr,Ptr dstPtr,short srcRow,short dstRow,short height,
  56671.     short words,short seedH,short seedV)
  56672.     = 0xA839; 
  56673. æDT SeedFill((Ptr) srcPtr,(Ptr) dstPtr,(short) srcRow,(short) dstRow,(short) height,()
  56674.     short words,(short) seedH,(short) seedV);
  56675. æRI IV-24
  56676. æC  
  56677. Given a source bit image, SeedFill computes a destination bit image with 1’s only in
  56678. the pixels where paint can leak from the starting seed point, like the MacPaint
  56679. paint-bucket tool. SeedH and seedV specify horizontal and vertical offsets, in pixels,
  56680. from the beginning of the data pointed to by dstPtr, determining how far into the
  56681. destination bit image filling should begin. Calls to SeedFill are not clipped to the
  56682. current port and are not stored into QuickDraw pictures.
  56683.  
  56684. æKY CalcMask
  56685. æFc Quickdraw.h
  56686. æT Function
  56687. æTN A838
  56688. æD pascal void CalcMask(Ptr srcPtr,Ptr dstPtr,short srcRow,short dstRow,short height,
  56689.     short words)
  56690.     = 0xA838; 
  56691. æDT CalcMask((Ptr) srcPtr,(Ptr) dstPtr,(short) srcRow,(short) dstRow,(short) height,()
  56692.     short words);
  56693. æRI IV-24
  56694. æC 
  56695. Given a source bit image, CalcMask computes a destination bit image with 1’s only in
  56696. the pixels where paint could not leak from any of the outer edges, like the MacPaint
  56697. lasso tool. Calls to CalcMask are not clipped to the current port and are not stored
  56698. into QuickDraw pictures.
  56699.  
  56700. æKY CopyMask
  56701. æFc Quickdraw.h
  56702. æT Function
  56703. æTN A817
  56704. æD pascal void CopyMask(const BitMap *srcBits,const BitMap *maskBits,const BitMap *dstBits,
  56705.     const Rect *srcRect,const Rect *maskRect,const Rect *dstRect)
  56706.     = 0xA817; 
  56707. æDT CopyMask((const BitMap *) srcBits,(const BitMap *) maskBits,(const BitMap *) dstBits,(
  56708.     const Rect) * srcRect,(const Rect *) maskRect,(const Rect *) dstRect);
  56709. æMM
  56710. æRT 163
  56711. æRI IV-24, V-71
  56712. æC 
  56713. CopyMask is a new version of the CopyBits procedure; it transfers a bit image from
  56714. the source bitmap to the destination bitmap only where the corresponding bit of the
  56715. mask rectangle is a 1. (Note that the mask is specified as a rectangle instead of as
  56716. a handle to a region.) It can be used along with CalcMask to implement the lasso copy
  56717. as in MacPaint; it’s also useful for drawing icons. CopyMask doesn’t check for overlap
  56718. between the source and destination bitmaps, doesn’t stretch the bit image, and doesn’t
  56719. store into QuickDraw pictures. CopyMask does, however, respect the current port’s
  56720. visRgn and clipRgn if dstBits is the portBits of the current grafPort.
  56721.  
  56722. CopyMask is a new version of the CopyBits procedure, introduced in the Macintosh
  56723. Plus. It transfers an image from the source to the destination only where the corresponding
  56724. bit of the mask equals 1. The Macintosh II version will accept either a bitMap or
  56725. pixMap as the srcBits or dstBits parameters. The maskBits parameter must be a bitMap.
  56726.  
  56727. Like the Macintosh Plus version, CopyMask doesn’t send any of its drawing commands
  56728. through grafProc routines; thus CopyMask calls are not recorded in pictures. Unlike
  56729. the Macintosh Plus version, the Macintosh II version of CopyMask is able to stretch
  56730. the source and mask to fit the dstRect. The srcRect and maskRect should be the same
  56731. size. CopyMask uses the same low-level code as CopyBits, so all the same rules regarding
  56732. depth translation and color table translation apply.
  56733.  
  56734. During a CopyMask call, the foreground and background colors are applied to the
  56735. image. To avoid unwanted coloring, set the foreground to black and the background to
  56736. white before calling this routine.
  56737.  
  56738. æKY OpenPicture
  56739. æFc Quickdraw.h
  56740. æT Function
  56741. æTN A8F3
  56742. æD pascal PicHandle OpenPicture(const Rect *picFrame)
  56743.     = 0xA8F3; 
  56744. æDT PicHandle myVariable = OpenPicture((const Rect *) picFrame);
  56745. æMM
  56746. æRT 21
  56747. æRI I-189, V-96, P-86, 178
  56748. æC  
  56749. OpenPicture returns a handle to a new picture that has the given rectangle as its
  56750. picture frame, and tells QuickDraw to start saving as the picture definition all
  56751. calls to drawing routines and all picture comments (if any).
  56752.  
  56753. OpenPicture calls HidePen, so no drawing occurs on the screen while the picture is
  56754. open (unless you call ShowPen just after OpenPicture, or you called ShowPen previously
  56755. without balancing it by a call to HidePen).
  56756.  
  56757. When a picture is open, the current grafPort’s picSave field contains a handle to
  56758. information related to the picture definition. If you want to temporarily disable the
  56759. collection of routine calls and picture comments, you can save the current value of
  56760. this field, set the field to NIL, and later restore the saved value to resume the
  56761. picture definition.
  56762.  
  56763. Warning:  Do not call OpenPicture while another picture is already open.
  56764.  
  56765. Warning:  A grafPort’s clipRgn is initialized to an arbitrarily large
  56766.           region. You should always change the clipRgn to a smaller
  56767.           region before calling OpenPicture, or no drawing may occur
  56768.           when you call DrawPicture.
  56769.  
  56770. The OpenPicture routine has been modified to take advantage of QuickDraw’s new color
  56771. capabilities. If the current port is a cGrafPort, then OpenPicture automatically
  56772. opens a version 2 picture, as described in the previous section. As before, you close
  56773. the picture using ClosePicture and draw the picture using DrawPicture.
  56774.  
  56775. æKY PicComment
  56776. æFc Quickdraw.h
  56777. æT Function
  56778. æTN A8F2
  56779. æD pascal void PicComment(short kind,short dataSize,Handle dataHandle)
  56780.     = 0xA8F2; 
  56781. æDT PicComment((short) kind,(short) dataSize,(Handle) dataHandle);
  56782. æMM
  56783. æRT 72, 91, 175, 181
  56784. æRI I-189, N72-2, N91
  56785. æC  
  56786. PicComment inserts the specified comment into the definition of the currently open
  56787. picture. The kind parameter identifies the type of comment. DataHandle is a handle to
  56788. additional data if desired, and dataSize is the size of that data in bytes. If there’s
  56789. no additional data for the comment, dataHandle should be NIL and dataSize should be
  56790. 0. An application that processes the comments must include a procedure to do the
  56791. processing and store a pointer to it in the data structure pointed to by the grafProcs
  56792. field of the grafPort (see “Customizing QuickDraw Operations”).
  56793.  
  56794. Note:  The standard low-level procedure for processing picture comments
  56795.        simply ignores all comments.
  56796.  
  56797. æKY ClosePicture
  56798. æFc Quickdraw.h
  56799. æT Function
  56800. æTN A8F4
  56801. æD pascal void ClosePicture(void)
  56802.     = 0xA8F4; 
  56803. æDT ClosePicture()(void);
  56804. æMM
  56805. æRI I-189, P-86, 167
  56806. æC  
  56807. ClosePicture tells QuickDraw to stop saving routine calls and picture comments as the
  56808. definition of the currently open picture. You should perform one and only one ClosePicture
  56809. for every OpenPicture. ClosePicture calls ShowPen, balancing the HidePen call made by
  56810. OpenPicture.
  56811.  
  56812. æKY DrawPicture
  56813. æFc Quickdraw.h
  56814. æT Function
  56815. æTN A8F6
  56816. æD pascal void DrawPicture(PicHandle myPicture,const Rect *dstRect)
  56817.     = 0xA8F6; 
  56818. æDT DrawPicture((PicHandle) myPicture,(const Rect *) dstRect);
  56819. æMM
  56820. æRT 21,59
  56821. æRI I-190, N21, N35-1, N59-1, P-86, 169
  56822. æC  
  56823. DrawPicture takes the part of the given picture that’s inside the picture frame and
  56824. draws it in dstRect, expanding or shrinking it as necessary to align the borders of
  56825. the picture frame with dstRect. DrawPicture passes any picture comments to a low-level
  56826. procedure accessed indirectly through the grafProcs field of the grafPort (see PicComment
  56827. above).
  56828.  
  56829. Warning:  If you call DrawPicture with the initial, arbitrarily large
  56830.           clipRgn and the destination rectangle is offset from the
  56831.           picture frame, you may end up with an empty clipRgn, and no
  56832.           drawing will take place.
  56833.  
  56834. æKY KillPicture
  56835. æFc Quickdraw.h
  56836. æT Function
  56837. æTN A8F5
  56838. æD pascal void KillPicture(PicHandle myPicture)
  56839.     = 0xA8F5; 
  56840. æDT KillPicture((PicHandle) myPicture);
  56841. æMM
  56842. æRI I-190
  56843. æC  
  56844. KillPicture releases the memory occupied by the given picture. Use this only when
  56845. you’re completely through with a picture (unless the picture is a resource, in which
  56846. case use the Resource Manager procedure ReleaseResource).
  56847.  
  56848. æKY OpenPoly
  56849. æFc Quickdraw.h
  56850. æT Function
  56851. æTN A8CB
  56852. æD pascal PolyHandle OpenPoly(void)
  56853.     = 0xA8CB; 
  56854. æDT PolyHandle myVariable = OpenPoly()(void);
  56855. æMM
  56856. æRI I-190
  56857. æC  
  56858. OpenPoly returns a handle to a new polygon and tells QuickDraw to start saving the
  56859. polygon definition as specified by calls to line-drawing routines. While a polygon is
  56860. open, all calls to Line and LineTo affect the outline of the polygon. Only the line
  56861. endpoints affect the polygon definition; the pen mode, pattern, and size do not
  56862. affect it. In fact, OpenPoly calls HidePen, so no drawing occurs on the screen while
  56863. the polygon is open (unless you call ShowPen just after OpenPoly, or you called
  56864. ShowPen previously without balancing it by a call to HidePen).
  56865.  
  56866. A polygon should consist of a sequence of connected lines. Even though the on-screen
  56867. presentation of a polygon is clipped, the definition of a polygon is not; you can
  56868. define a polygon anywhere on the coordinate plane.
  56869.  
  56870. When a polygon is open, the current grafPort’s polySave field contains a handle to
  56871. information related to the polygon definition. If you want to temporarily disable the
  56872. polygon definition, you can save the current value of this field, set the field to
  56873. NIL, and later restore the saved value to resume the polygon definition.
  56874.  
  56875. Warning:  Do not call OpenPoly while a region or another polygon is
  56876.           already open.
  56877.  
  56878. Note:  Polygons are limited to 32K bytes; you can determine the polygon
  56879.        size while it’s being formed by calling the Memory Manager function
  56880.        GetHandleSize.
  56881.  
  56882. æKY ClosePoly
  56883. æFc Quickdraw.h
  56884. æT Function
  56885. æTN A8CC
  56886. æD pascal void ClosePoly(void)
  56887.     = 0xA8CC; 
  56888. æDT ClosePoly()(void);
  56889. æMM
  56890. æRI I-190
  56891. æC  
  56892. Assembly-language note:  The macro you invoke to call ClosePoly from
  56893.                          assembly language is named _ClosePgon.
  56894.  
  56895. ClosePoly tells QuickDraw to stop saving the definition of the currently open polygon
  56896. and computes the polyBBox rectangle. You should perform one and only one ClosePoly
  56897. for every OpenPoly. ClosePoly calls ShowPen, balancing the HidePen call made by
  56898. OpenPoly.
  56899.  
  56900. Here’s an example of how to open a polygon, define it as a triangle, close it, and
  56901. draw it:
  56902.  
  56903.   triPoly := OpenPoly;           {save handle and begin collecting stuff}
  56904.       MoveTo(300,100);           {move to first point and }
  56905.       LineTo(400,200);           {          form          }
  56906.       LineTo(200,200);           {          the           }
  56907.       LineTo(300,100);           {        triangle        }
  56908.   ClosePoly;                     {stop collecting stuff}
  56909.   FillPoly(triPoly,gray);        {draw it on the screen}
  56910.   KillPoly(triPoly)              {we're all done}
  56911.  
  56912. æKY KillPoly
  56913. æFc Quickdraw.h
  56914. æT Function
  56915. æTN A8CD
  56916. æD pascal void KillPoly(PolyHandle poly)
  56917.     = 0xA8CD; 
  56918. æDT KillPoly((PolyHandle) poly);
  56919. æMM
  56920. æRI I-191
  56921. æC  
  56922. KillPoly releases the memory occupied by the given polygon. Use this only when you’re
  56923. completely through with a polygon.
  56924.  
  56925. æKY OffsetPoly
  56926. æFc Quickdraw.h
  56927. æT Function
  56928. æTN A8CE
  56929. æD pascal void OffsetPoly(PolyHandle poly,short dh,short dv)
  56930.     = 0xA8CE; 
  56931. æDT OffsetPoly((PolyHandle) poly,(short) dh,(short) dv);
  56932. æRI I-191
  56933. æC  
  56934. OffsetPoly moves the polygon on the coordinate plane, a distance of dh horizontally
  56935. and dv vertically. This doesn’t affect the screen unless you subsequently call a
  56936. routine to draw the polygon. If dh and dv are positive, the movement is to the right
  56937. and down; if either is negative, the corresponding movement is in the opposite direction.
  56938. The polygon retains its shape and size.
  56939.  
  56940. Note:  OffsetPoly is an especially efficient operation, because the data
  56941.        defining a polygon is stored relative to the first point of the
  56942.        polygon and so isn’t actually changed by OffsetPoly.
  56943.  
  56944. æKY FramePoly
  56945. æFc Quickdraw.h
  56946. æT Function
  56947. æTN A8C6
  56948. æD pascal void FramePoly(PolyHandle poly)
  56949.     = 0xA8C6; 
  56950. æDT FramePoly((PolyHandle) poly);
  56951. æMM
  56952. æRI I-192
  56953. æC  
  56954. FramePoly plays back the line-drawing routine calls that define the given polygon,
  56955. using the current grafPort’s pen pattern, mode, and size. The pen will hang below and
  56956. to the right of each point on the boundary of the polygon;
  56957. thus, the polygon drawn will extend beyond the right and bottom edges of
  56958. poly^^.polyBBox by the pen width and pen height, respectively. All other graphic
  56959. operations occur strictly within the boundary of the polygon, as for other shapes.
  56960. You can see this difference in Figure 25, where each of the polygons is shown with
  56961. its polyBBox.
  56962.  
  56963. •••Refer to Figure 25.•••
  56964.  
  56965. Figure 25–Drawing Polygons
  56966.  
  56967. If a polygon is open and being formed, FramePoly affects the outline of the polygon
  56968. just as if the line-drawing routines themselves had been called. If a region is open
  56969. and being formed, the outside outline of the polygon being framed is mathematically
  56970. added to the region’s boundary.
  56971.  
  56972. æKY PaintPoly
  56973. æFc Quickdraw.h
  56974. æT Function
  56975. æTN A8C7
  56976. æD pascal void PaintPoly(PolyHandle poly)
  56977.     = 0xA8C7; 
  56978. æDT PaintPoly((PolyHandle) poly);
  56979. æMM
  56980. æRI I-192
  56981. æC  
  56982. PaintPoly paints the specified polygon with the current grafPort’s pen pattern and
  56983. pen mode. The polygon is filled with the pnPat, according to the pattern transfer
  56984. mode specified by pnMode. The pen location is not changed by this procedure.
  56985.  
  56986. æKY ErasePoly
  56987. æFc Quickdraw.h
  56988. æT Function
  56989. æTN A8C8
  56990. æD pascal void ErasePoly(PolyHandle poly)
  56991.     = 0xA8C8; 
  56992. æDT ErasePoly((PolyHandle) poly);
  56993. æMM
  56994. æRI I-192
  56995. æC  
  56996. ErasePoly paints the specified polygon with the current grafPort’s background pattern
  56997. bkPat (in patCopy mode). The pnPat and pnMode are ignored; the pen location is not
  56998. changed.
  56999.  
  57000. æKY InvertPoly
  57001. æFc Quickdraw.h
  57002. æT Function
  57003. æTN A8C9
  57004. æD pascal void InvertPoly(PolyHandle poly)
  57005.     = 0xA8C9; 
  57006. æDT InvertPoly((PolyHandle) poly);
  57007. æMM
  57008. æRI I-192
  57009. æC  
  57010. InvertPoly inverts the pixels enclosed by the specified polygon:  Every white pixel
  57011. becomes black and every black pixel becomes white. The grafPort’s pnPat, pnMode, and
  57012. bkPat are all ignored; the pen location is not changed.
  57013.  
  57014. æKY FillPoly
  57015. æFc Quickdraw.h
  57016. æT Function
  57017. æTN A8CA
  57018. æD pascal void FillPoly(PolyHandle poly,Pattern pat)
  57019.     = 0xA8CA; 
  57020. æDT FillPoly((PolyHandle) poly,(Pattern) pat);
  57021. æMM
  57022. æRI I-192, N27-6
  57023. æC  
  57024. FillPoly fills the specified polygon with the given pattern (in patCopy mode). The
  57025. grafPort’s pnPat, pnMode, and bkPat are all ignored; the pen location is not changed.
  57026.  
  57027. æKY SetPt
  57028. æFc Quickdraw.h
  57029. æT Function
  57030. æTN A880
  57031. æD pascal void SetPt(Point *pt,short h,short v)
  57032.     = 0xA880; 
  57033. æDT SetPt((Point *) pt,(short) h,(short) v);
  57034. æRI I-193
  57035. æC 
  57036. SetPt assigns the two given coordinates to the point pt.
  57037.  
  57038. æKY LocalToGlobal
  57039. æFc Quickdraw.h
  57040. æT Function
  57041. æTN A870
  57042. æD pascal void LocalToGlobal(Point *pt)
  57043.     = 0xA870; 
  57044. æDT LocalToGlobal((Point *) pt);
  57045. æRI I-193, P-77, 176
  57046. æC  
  57047. LocalToGlobal converts the given point from the current grafPort’s local coordinate
  57048. system into a global coordinate system with the origin (0,0) at the top left corner
  57049. of the port’s bit image (such as the screen). This global point can then be compared
  57050. to other global points, or be changed into the local coordinates of another grafPort.
  57051.  
  57052. Since a rectangle is defined by two points, you can convert a rectangle into global
  57053. coordinates by performing two LocalToGlobal calls. You can also convert a rectangle,
  57054. region, or polygon into global coordinates by calling OffsetRect, OffsetRgn, or
  57055. OffsetPoly. For examples, see GlobalToLocal below.
  57056.  
  57057. æKY GlobalToLocal
  57058. æFc Quickdraw.h
  57059. æT Function
  57060. æTN A871
  57061. æD pascal void GlobalToLocal(Point *pt)
  57062.     = 0xA871; 
  57063. æDT GlobalToLocal((Point *) pt);
  57064. æRI I-193, P-77, 110, 174
  57065. æC  
  57066. GlobalToLocal takes a point expressed in global coordinates (with the top left corner
  57067. of the bit image as coordinate (0,0)) and converts it into the local coordinates of
  57068. the current grafPort. The global point can be obtained with the LocalToGlobal call
  57069. (see above). For example, suppose a game draws a “ball” within a rectangle named
  57070. ballRect, defined in the grafPort named gamePort (as illustrated in Figure 26). If
  57071. you want to draw that ball in the grafPort named selectPort, you can calculate the
  57072. ball’s selectPort coordinates like this:
  57073.  
  57074.   SetPort(gamePort);                     {start in origin port}
  57075.   selectBall := ballRect;                {make a copy to be moved}
  57076.   LocalToGlobal(selectBall.topLeft);     {put both corners into }
  57077.   LocalToGlobal(selectBall.botRight);    { global coordinates}
  57078.  
  57079.   SetPort(selectPort);                   {switch to destination port}
  57080.   GlobalToLocal(selectBall.topLeft);     {put both corners into }
  57081.   GlobalToLocal(selectBall.botRight);    { these local coordinates}
  57082.   FillOval(selectBall,ballColor)         {draw the ball}
  57083.  
  57084. •••Refer to Figure 26.•••
  57085.  
  57086. Figure 26–Converting between Coordinate Systems
  57087.  
  57088. You can see from Figure 26 that LocalToGlobal and GlobalToLocal simply offset the
  57089. coordinates of the rectangle by the coordinates of the top left corner of the local
  57090. grafPort’s portBits.bounds rectangle. You could also do this with OffsetRect. In
  57091. fact, the way to convert regions and polygons from one coordinate system to another
  57092. is with OffsetRgn or OffsetPoly rather than LocalToGlobal and GlobalToLocal. For
  57093. example, if myRgn were a region enclosed by a rectangle having the same coordinates
  57094. as ballRect in gamePort, you could convert the region to global coordinates with
  57095.  
  57096.   OffsetRgn(myRgn,-20,-40)
  57097.  
  57098. and then convert it to the coordinates of the selectPort grafPort with
  57099.  
  57100.   OffsetRgn(myRgn,15,-30)
  57101.  
  57102. æKY Random
  57103. æFc Quickdraw.h
  57104. æT Function
  57105. æTN A861
  57106. æD pascal short Random(void)
  57107.     = 0xA861; 
  57108. æDT short myVariable = Random()(void);
  57109. æRI I-194
  57110. æC  
  57111. This function returns a pseudo-random integer, uniformly distributed in the range
  57112. –32767 through 32767. The value the sequence starts from depends on the global variable
  57113. randSeed, which InitGraf initializes to 1. To start the sequence over again from
  57114. where it began, reset randSeed to 1. To start a new sequence each time, you must
  57115. reset randSeed to a random number.
  57116.  
  57117. Note:  You can start a new sequence by storing the current date and time
  57118.        in randSeed; see GetDateTime in the Operating System Utilities chapter.
  57119.  
  57120. Assembly-language note:  From assembly language, it’s better to start a new
  57121.                          sequence by storing the value of the system global
  57122.                          variable RndSeed in randSeed.
  57123.  
  57124. æKY StuffHex
  57125. æFc Quickdraw.h
  57126. æT Function
  57127. æTN A866
  57128. æD pascal void StuffHex(Ptr thingPtr,const Str255 s)
  57129.     = 0xA866; 
  57130. æDT StuffHex((Ptr) thingPtr,(const Str255) s);
  57131. æRI I-195, P-81
  57132. æC  
  57133. StuffHex stores bits (expressed as a string of hexadecimal digits) into any data
  57134. structure. You can easily create a pattern in your program with StuffHex
  57135. (though more likely, you’ll store patterns in a resource file). For example,
  57136.  
  57137.   StuffHex(@stripes,'0102040810204080')
  57138.  
  57139. places a striped pattern into the pattern variable named stripes.
  57140.  
  57141. Warning:  There’s no range checking on the size of the destination variable.
  57142.           It’s easy to overrun the variable and destroy something if you
  57143.           don’t know what you’re doing.
  57144.  
  57145. æKY GetPixel
  57146. æFc Quickdraw.h
  57147. æT Function
  57148. æTN A865
  57149. æD pascal Boolean GetPixel(short h,short v)
  57150.     = 0xA865; 
  57151. æDT Boolean myVariable = GetPixel((short) h,(short) v);
  57152. æRI I-195
  57153. æC  
  57154. GetPixel looks at the pixel associated with the given coordinate point and returns
  57155. TRUE if it’s black or FALSE if it’s white. The selected pixel is immediately below
  57156. and to the right of the point whose coordinates are given in h and v, in the local
  57157. coordinates of the current grafPort. There’s no guarantee that the specified pixel
  57158. actually belongs to the port, however; it may have been drawn by a port overlapping
  57159. the current one. To see if the point indeed belongs to the current port, you could
  57160. call PtInRgn(pt, thePort^.visRgn).
  57161.  
  57162. Note:  To find out which window’s grafPort a point lies in, you call the
  57163.        Window Manager function FindWindow, as described in the Window
  57164.        Manager chapter.
  57165.  
  57166. æKY ScalePt
  57167. æFc Quickdraw.h
  57168. æT Function
  57169. æTN A8F8
  57170. æD pascal void ScalePt(Point *pt,const Rect *srcRect,const Rect *dstRect)
  57171.     = 0xA8F8; 
  57172. æDT ScalePt((Point *) pt,(const Rect *) srcRect,(const Rect *) dstRect);
  57173. æRI I-195
  57174. æC  
  57175. A width and height are passed in pt; the horizontal component of pt is the width, and
  57176. its vertical component is the height. ScalePt scales these measurements as follows
  57177. and returns the result in pt:  It multiplies the given width by the ratio of dstRect’s
  57178. width to srcRect’s width, and multiplies the given height by the ratio of dstRect’s
  57179. height to srcRect’s height.
  57180.  
  57181. ScalePt can be used, for example, for scaling the pen dimensions. In Figure 27, where
  57182. dstRect’s width is twice srcRect’s width and its height is three times srcRect’s
  57183. height, the pen width is scaled from 3 to 6 and the pen height is scaled from 2 to
  57184. 6.
  57185.  
  57186. Note:  The minimum value ScalePt will return is (1,1).
  57187.  
  57188. •••Refer to Figure 27.•••
  57189.  
  57190. Figure 27–ScalePt and MapPt
  57191.  
  57192. æKY MapPt
  57193. æFc Quickdraw.h
  57194. æT Function
  57195. æTN A8F9
  57196. æD pascal void MapPt(Point *pt,const Rect *srcRect,const Rect *dstRect)
  57197.     = 0xA8F9; 
  57198. æDT MapPt((Point *) pt,(const Rect *) srcRect,(const Rect *) dstRect);
  57199. æRI I-196
  57200. æC  
  57201. Given a point within srcRect, MapPt maps it to a similarly located point within
  57202. dstRect (that is, to where it would fall if it were part of a drawing being expanded
  57203. or shrunk to fit dstRect). The result is returned in pt. A corner point of srcRect
  57204. would be mapped to the corresponding corner point of dstRect, and the center of
  57205. srcRect to the center of dstRect. In Figure 27, the point
  57206. (3,2) in srcRect is mapped to (18,7) in dstRect. SrcRect and dstRect may overlap, and
  57207. pt need not actually be within srcRect.
  57208.  
  57209. Note:  Remember, if you’re going to draw inside the destination rectangle,
  57210.        you’ll probably also want to scale the pen size accordingly with ScalePt.
  57211.  
  57212. æKY MapRect
  57213. æFc Quickdraw.h
  57214. æT Function
  57215. æTN A8FA
  57216. æD pascal void MapRect(Rect *r,const Rect *srcRect,const Rect *dstRect)
  57217.     = 0xA8FA; 
  57218. æDT MapRect((Rect *) r,(const Rect *) srcRect,(const Rect *) dstRect);
  57219. æRI I-196
  57220. æC  
  57221. Given a rectangle within srcRect, MapRect maps it to a similarly located rectangle
  57222. within dstRect by calling MapPt to map the top left and bottom right corners of the
  57223. rectangle. The result is returned in r.
  57224.  
  57225. æKY MapRgn
  57226. æFc Quickdraw.h
  57227. æT Function
  57228. æTN A8FB
  57229. æD pascal void MapRgn(RgnHandle rgn,const Rect *srcRect,const Rect *dstRect)
  57230.     = 0xA8FB; 
  57231. æDT MapRgn((RgnHandle) rgn,(const Rect *) srcRect,(const Rect *) dstRect);
  57232. æMM
  57233. æRI I-196
  57234. æC  
  57235. Given a region within srcRect, MapRgn maps it to a similarly located region within
  57236. dstRect by calling MapPt to map all the points in the region.
  57237.  
  57238. Note:  MapRgn is useful for determining whether a region operation will
  57239.        exceed available memory:  By mapping a large region into a smaller
  57240.        one and performing the operation (without actually drawing), you
  57241.        can estimate how much memory will be required by the anticipated
  57242.        operation.
  57243.  
  57244. æKY MapPoly
  57245. æFc Quickdraw.h
  57246. æT Function
  57247. æTN A8FC
  57248. æD pascal void MapPoly(PolyHandle poly,const Rect *srcRect,const Rect *dstRect)
  57249.     = 0xA8FC; 
  57250. æDT MapPoly((PolyHandle) poly,(const Rect *) srcRect,(const Rect *) dstRect);
  57251. æRI I-197
  57252. æC  
  57253. Given a polygon within srcRect, MapPoly maps it to a similarly located polygon within
  57254. dstRect by calling MapPt to map all the points that define the polygon.
  57255.  
  57256. Note:  Like MapRgn, MapPoly is useful for determining whether a polygon
  57257.        operation will succeed.
  57258.  
  57259. æKY SetStdProcs
  57260. æFc Quickdraw.h
  57261. æT Function
  57262. æTN A8EA
  57263. æD pascal void SetStdProcs(QDProcs *procs)
  57264.     = 0xA8EA; 
  57265. æDT SetStdProcs((QDProcs *) procs);
  57266. æRI I-198
  57267. æC  
  57268. This procedure sets all the fields of the given QDProcs record to point to the standard
  57269. low-level routines. You can then change the ones you wish to point to your own routines.
  57270. For example, if your procedure that processes picture comments is named MyComments,
  57271. you’ll store @MyComments in the commentProc field of the QDProcs record.
  57272.  
  57273. You can either write your own routines to completely replace the standard ones, or do
  57274. preprocessing and then call the standard routines. The routines you install must of
  57275. course have the same calling sequences as the standard routines, which are described
  57276. below.
  57277.  
  57278. Note:  These low-level routines should be called only from your
  57279.        customized routines.
  57280.  
  57281. The standard drawing routines tell which graphic operation to perform from a parameter
  57282. of type GrafVerb:
  57283.  
  57284. TYPE  GrafVerb = (frame,paint,erase,invert,fill);
  57285.  
  57286. When the grafVerb is fill, the pattern to use during filling is passed in the fillPat
  57287. field of the grafPort.
  57288.  
  57289. æKY StdRect
  57290. æFc Quickdraw.h
  57291. æT Function
  57292. æTN A8A0
  57293. æD pascal void StdRect(GrafVerb verb,const Rect *r)
  57294.     = 0xA8A0; 
  57295. æDT StdRect((GrafVerb) verb,(const Rect *) r);
  57296. æMM
  57297. æRI I-198
  57298. æC 
  57299. StdRect is the standard low-level routine for drawing a rectangle. It draws the given
  57300. rectangle according to the specified grafVerb.
  57301.  
  57302. æKY StdRRect
  57303. æFc Quickdraw.h
  57304. æT Function
  57305. æTN A8AF
  57306. æD pascal void StdRRect(GrafVerb verb,const Rect *r,short ovalWidth,short ovalHeight)
  57307.     = 0xA8AF; 
  57308. æDT StdRRect((GrafVerb) verb,(const Rect *) r,(short) ovalWidth,(short) ovalHeight);
  57309. æMM
  57310. æRI I-198
  57311. æC  
  57312. StdRRect is the standard low-level routine for drawing a rounded-corner rectangle. It
  57313. draws the given rounded-corner rectangle according to the specified grafVerb. OvalWidth
  57314. and ovalHeight specify the diameters of curvature for the corners.
  57315.  
  57316. æKY StdOval
  57317. æFc Quickdraw.h
  57318. æT Function
  57319. æTN A8B6
  57320. æD pascal void StdOval(GrafVerb verb,const Rect *r)
  57321.     = 0xA8B6; 
  57322. æDT StdOval((GrafVerb) verb,(const Rect *) r);
  57323. æMM
  57324. æRI I-199
  57325. æC  
  57326. StdOval is the standard low-level routine for drawing an oval. It draws an oval
  57327. inside the given rectangle according to the specified grafVerb.
  57328.  
  57329. æKY StdArc
  57330. æFc Quickdraw.h
  57331. æT Function
  57332. æTN A8BD
  57333. æD pascal void StdArc(GrafVerb verb,const Rect *r,short startAngle,short arcAngle)
  57334.     = 0xA8BD; 
  57335. æDT StdArc((GrafVerb) verb,(const Rect *) r,(short) startAngle,(short) arcAngle);
  57336. æMM
  57337. æRI I-199
  57338. æC  
  57339. StdArc is the standard low-level routine for drawing an arc or a wedge. It draws an
  57340. arc or wedge of the oval that fits inside the given rectangle, beginning at startAngle
  57341. and extending to arcAngle. The grafVerb specifies the graphic operation; if it’s the
  57342. frame operation, an arc is drawn; otherwise, a wedge is drawn.
  57343.  
  57344. æKY StdPoly
  57345. æFc Quickdraw.h
  57346. æT Function
  57347. æTN A8C5
  57348. æD pascal void StdPoly(GrafVerb verb,PolyHandle poly)
  57349.     = 0xA8C5; 
  57350. æDT StdPoly((GrafVerb) verb,(PolyHandle) poly);
  57351. æMM
  57352. æRI I-199, N27-6
  57353. æC 
  57354. StdPoly is the standard low-level routine for drawing a polygon. It draws the given
  57355. polygon according to the specified grafVerb.
  57356.  
  57357. æKY StdRgn
  57358. æFc Quickdraw.h
  57359. æT Function
  57360. æTN A8D1
  57361. æD pascal void StdRgn(GrafVerb verb,RgnHandle rgn)
  57362.     = 0xA8D1; 
  57363. æDT StdRgn((GrafVerb) verb,(RgnHandle) rgn);
  57364. æMM
  57365. æRI I-199
  57366. æC 
  57367. StdRgn is the standard low-level routine for drawing a region. It draws the given
  57368. region according to the specified grafVerb.
  57369.  
  57370. æKY StdBits
  57371. æFc Quickdraw.h
  57372. æT Function
  57373. æTN A8EB
  57374. æD pascal void StdBits(const BitMap *srcBits,const Rect *srcRect,const Rect *dstRect,
  57375.     short mode,RgnHandle maskRgn)
  57376.     = 0xA8EB; 
  57377. æDT StdBits((const BitMap *) srcBits,(const Rect *) srcRect,(const Rect *) dstRect,()
  57378.     short mode,(RgnHandle) maskRgn);
  57379. æMM
  57380. æRI I-199
  57381. æC  
  57382. StdBits is the standard low-level routine for doing bit transfer. It transfers a bit
  57383. image between the given bit map and thePort^.portBits, just as if CopyBits were
  57384. called with the same parameters and with a destination bit map equal to thePort^.portBits.
  57385.  
  57386. æKY StdComment
  57387. æFc Quickdraw.h
  57388. æT Function
  57389. æTN A8F1
  57390. æD pascal void StdComment(short kind,short dataSize,Handle dataHandle)
  57391.     = 0xA8F1; 
  57392. æDT StdComment((short) kind,(short) dataSize,(Handle) dataHandle);
  57393. æMM
  57394. æRI I-199
  57395. æC  
  57396. StdComment is the standard low-level routine for processing a picture comment. The
  57397. kind parameter identifies the type of comment. DataHandle is a handle to additional
  57398. data, and dataSize is the size of that data in bytes. If there’s no additional data
  57399. for the comment, dataHandle will be NIL and dataSize will be 0. StdComment simply
  57400. ignores the comment.
  57401.  
  57402. æKY StdTxMeas
  57403. æFc Quickdraw.h
  57404. æT Function
  57405. æTN A8ED
  57406. æD pascal short StdTxMeas(short byteCount,Ptr textAddr,Point *numer,Point *denom,
  57407.     FontInfo *info)
  57408.     = 0xA8ED; 
  57409. æDT short myVariable = StdTxMeas((short) byteCount,(Ptr) textAddr,(Point *) numer,(Point *) denom,(
  57410.     FontInfo) * info);
  57411. æMM
  57412. æRI I-199
  57413. æC  
  57414. StdTxMeas is the standard low-level routine for measuring text width. It returns the
  57415. width of the text stored in the arbitrary structure in memory specified by textAddr,
  57416. starting with the first byte and continuing for byteCount bytes. Numer and denom
  57417. specify the scaling as in the StdText procedure; note that StdTxMeas may change
  57418. them.
  57419.  
  57420. æKY StdGetPic
  57421. æFc Quickdraw.h
  57422. æT Function
  57423. æTN A8EE
  57424. æD pascal void StdGetPic(Ptr dataPtr,short byteCount)
  57425.     = 0xA8EE; 
  57426. æDT StdGetPic((Ptr) dataPtr,(short) byteCount);
  57427. æRI I-200
  57428. æC 
  57429. StdGetPic is the standard low-level routine for retrieving information from the
  57430. definition of a picture. It retrieves the next byteCount bytes from the definition of
  57431. the currently open picture and stores them in the data structure pointed to by dataPtr.
  57432.  
  57433. æKY StdPutPic
  57434. æFc Quickdraw.h
  57435. æT Function
  57436. æTN A8F0
  57437. æD pascal void StdPutPic(Ptr dataPtr,short byteCount)
  57438.     = 0xA8F0; 
  57439. æDT StdPutPic((Ptr) dataPtr,(short) byteCount);
  57440. æMM
  57441. æRI I-200
  57442. æC 
  57443. StdPutPic is the standard low-level routine for saving information as the definition
  57444. of a picture. It saves as the definition of the currently open picture the drawing
  57445. commands stored in the data structure pointed to by dataPtr, starting with the first
  57446. byte and continuing for the next byteCount bytes.
  57447.  
  57448. æKY AddPt
  57449. æFc Quickdraw.h
  57450. æT Function
  57451. æTN A87E
  57452. æD pascal void AddPt(Point src,Point *dst)
  57453.     = 0xA87E; 
  57454. æDT AddPt((Point) src,(Point *) dst);
  57455. æRI I-193
  57456. æC  
  57457. AddPt adds the coordinates of srcPt to the coordinates of dstPt, and returns the
  57458. result in dstPt.
  57459.  
  57460. æKY subpt
  57461. æFc Quickdraw.h
  57462. æT Function
  57463. æD void subpt(Point *src,Point *dst); 
  57464. æDT subpt((Point *) src,(Point *) dst);
  57465. æRI I-193
  57466. æC  
  57467. SubPt subtracts the coordinates of srcPt from the coordinates of dstPt, and returns
  57468. the result in dstPt.
  57469.  
  57470. Note:  To get the results of coordinate subtraction returned as a function
  57471.        result, you can use the Toolbox Utility function DeltaPoint.
  57472.  
  57473. æKY EqualPt
  57474. æFc Quickdraw.h
  57475. æT Function
  57476. æTN A881
  57477. æD pascal Boolean EqualPt(Point pt1,Point pt2)
  57478.     = 0xA881; 
  57479. æDT Boolean myVariable = EqualPt((Point) pt1,(Point) pt2);
  57480. æRI I-193
  57481. æC  
  57482. EqualPt compares the two given points and returns TRUE if they’re equal or FALSE if
  57483. not.
  57484.  
  57485. æKY PtInRect
  57486. æFc Quickdraw.h
  57487. æT Function
  57488. æTN A8AD
  57489. æD pascal Boolean PtInRect(Point pt,const Rect *r)
  57490.     = 0xA8AD; 
  57491. æDT Boolean myVariable = PtInRect((Point) pt,(const Rect *) r);
  57492. æRI I-175
  57493. æC  
  57494. PtInRect determines whether the pixel below and to the right of the given coordinate
  57495. point is enclosed in the specified rectangle, and returns TRUE if so or FALSE if
  57496. not.
  57497.  
  57498. æKY Pt2Rect
  57499. æFc Quickdraw.h
  57500. æT Function
  57501. æTN A8AC
  57502. æD pascal void Pt2Rect(Point pt1,Point pt2,Rect *dstRect)
  57503.     = 0xA8AC; 
  57504. æDT Pt2Rect((Point) pt1,(Point) pt2,(Rect *) dstRect);
  57505. æRI I-175
  57506. æC  
  57507. Pt2Rect returns the smallest rectangle that encloses the two given points.
  57508.  
  57509. æKY PtToAngle
  57510. æFc Quickdraw.h
  57511. æT Function
  57512. æTN A8C3
  57513. æD pascal void PtToAngle(const Rect *r,Point pt,short *angle)
  57514.     = 0xA8C3; 
  57515. æDT PtToAngle((const Rect *) r,(Point) pt,(short *) angle);
  57516. æRI I-175
  57517. æC  
  57518. PtToAngle calculates an integer angle between a line from the center of the rectangle
  57519. to the given point and a line from the center of the rectangle pointing straight up
  57520. (12 o’clock high). The angle is in degrees from 0 to 359, measured clockwise from 12
  57521. o’clock, with 90 degrees at 3 o’clock, 180 at
  57522. 6 o’clock, and 270 at 9 o’clock. Other angles are measured relative to the rectangle:
  57523.  If the line to the given point goes through the top right corner of the rectangle,
  57524. the angle returned is 45 degrees, even if the rectangle isn’t square; if it goes
  57525. through the bottom right corner, the angle is 135 degrees, and so on (see Figure
  57526. 20).
  57527.  
  57528. •••Refer to Figure 20.•••
  57529.  
  57530. Figure 20–PtToAngle
  57531.  
  57532. The angle returned might be used as input to one of the procedures that manipulate
  57533. arcs and wedges, as described below under “Graphic Operations on Arcs and Wedges”.
  57534.  
  57535. æKY PtInRgn
  57536. æFc Quickdraw.h
  57537. æT Function
  57538. æTN A8E8
  57539. æD pascal Boolean PtInRgn(Point pt,RgnHandle rgn)
  57540.     = 0xA8E8; 
  57541. æDT Boolean myVariable = PtInRgn((Point) pt,(RgnHandle) rgn);
  57542. æRI I-185
  57543. æC  
  57544. PtInRgn checks whether the pixel below and to the right of the given coordinate point
  57545. is within the specified region, and returns TRUE if so or FALSE if not.
  57546.  
  57547. æKY StdText
  57548. æFc Quickdraw.h
  57549. æT Function
  57550. æTN A882
  57551. æD pascal void StdText(short count,Ptr textAddr,Point numer,Point denom)
  57552.     = 0xA882; 
  57553. æDT StdText((short) count,(Ptr) textAddr,(Point) numer,(Point) denom);
  57554. æMM
  57555. æRI I-198, N27-5
  57556. æC  
  57557. StdText is the standard low-level routine for drawing text. It draws text from the
  57558. arbitrary structure in memory specified by textBuf, starting from the first byte and
  57559. continuing for byteCount bytes. Numer and denom specify the scaling factor:  numer.v
  57560. over denom.v gives the vertical scaling, and numer.h over denom.h gives the horizontal
  57561. scaling.
  57562.  
  57563. æKY StdLine
  57564. æFc Quickdraw.h
  57565. æT Function
  57566. æTN A890
  57567. æD pascal void StdLine(Point newPt)
  57568.     = 0xA890; 
  57569. æDT StdLine((Point) newPt);
  57570. æMM
  57571. æRI I-198, N27-5, 6
  57572. æC  
  57573. StdLine is the standard low-level routine for drawing a line. It draws a line from
  57574. the current pen location to the location specified (in local coordinates) by newPt.
  57575.  
  57576. æKY OpenCPort
  57577. æFc Quickdraw.h
  57578. æT Function
  57579. æTN AA00
  57580. æD pascal void OpenCPort(CGrafPtr port)
  57581.     = 0xAA00; 
  57582. æDT OpenCPort((CGrafPtr) port);
  57583. æMM
  57584. æRI V-67
  57585. æC  
  57586. The OpenCPort procedure is analogous to OpenPort, except it opens a cGrafPort instead
  57587. of a grafPort. You will rarely need to use this call, since OpenCPort is called by
  57588. NewCWindow and GetNewCWindow, as well as by the Dialog Manager when the appropriate
  57589. color resources are present.  OpenCPort allocates storage for all the structures in
  57590. the cGrafPort, and then calls InitCPort to initialize them.  The new structures
  57591. allocated are the portPixMap, the pnPixPat, the fillPixPat, the bkPixPat, and the
  57592. grafVars handle.  The GrafVars record structure is shown below:
  57593.  
  57594. TYPE
  57595. GrafVars = RECORD
  57596.              rgbOpColor:        RGBColor;    {color for addPin, subPin, and }
  57597.                                              { blend}
  57598.              rgbHiliteColor:    RGBColor;    {color for highlighting}
  57599.              pmFgColor:         Handle;      {Palette handle for foreground }
  57600.                                              { color}
  57601.              pmFgIndex:         INTEGER;     {index value for foreground}
  57602.              pmBkColor:         Handle;      {Palette handle for background }
  57603.                                              { color}
  57604.              pmBkIndex:         INTEGER;     {index value for background}
  57605.              pmFlags:           INTEGER;     {Flags for Palette Manager}
  57606.            END;
  57607.  
  57608. The rgbOpColor field is initialized as black, and the rgbHiliteColor field is initialized
  57609. as the default HiliteRGB. All the rest of the GrafVars fields are initially zero.
  57610.  
  57611. The portPixMap is not allocated a color table of its own. When InitCPort is called,
  57612. the handle to the current device’s color table is copied into the portPixMap.
  57613.  
  57614. æKY InitCPort
  57615. æFc Quickdraw.h
  57616. æT Function
  57617. æTN AA01
  57618. æD pascal void InitCPort(CGrafPtr port)
  57619.     = 0xAA01; 
  57620. æDT InitCPort((CGrafPtr) port);
  57621. æMM
  57622. æRI V-67
  57623. æC  
  57624. The InitCPort procedure does not allocate any storage. It merely initializes all the
  57625. fields in the cGrafPort to their default values.  All old fields are initialized to
  57626. the same values as a grafPort’s fields. New fields are given the following values:
  57627.  
  57628.   portPixMap:     copied from theGDevice^^.GDPMap
  57629.   portVersion:    $C000
  57630.   grafVars:       opColor initialized to black, rgbHiliteColor
  57631.                   initialized as default HiliteRGB.  All other
  57632.                   fields are initialized as 0.
  57633.   chExtra:        0
  57634.   pnLocHFrac:     1/2
  57635.   bkPixPat:       white
  57636.   rgbFgColor:     black
  57637.   rgbBkColor:     white
  57638.   pnPixPat:       black
  57639.   fillPixPat:     black
  57640.  
  57641. The default portPixMap is set to be the same as the current device’s pixMap. This
  57642. allows you to create an offscreen port that is identical to the screen’s grafPort or
  57643. cGrafPort for drawing offscreen. If you want to use a different set of colors for
  57644. offscreen drawing, you should create a new gDevice, and set it as the current gDevice
  57645. before opening the cGrafPort. Refer to the section on offscreen bitMaps in the Graphics
  57646. Devices chapter for more details.
  57647.  
  57648. As mentioned above, InitCPort does not copy the data from the current device’s color
  57649. table to the portPixMap’s color table. It simply replaces whatever is in the pmTable
  57650. field with a copy of the handle to the current device’s color table.
  57651.  
  57652. If you try to initialize a grafPort using InitCPort, it will simply return without
  57653. doing anything.
  57654.  
  57655. æKY CloseCPort
  57656. æFc Quickdraw.h
  57657. æT Function
  57658. æTN A87D
  57659. æD pascal void CloseCPort(CGrafPtr port)
  57660.     = 0xA87D; 
  57661. æDT CloseCPort((CGrafPtr) port);
  57662. æMM
  57663. æRI V-68
  57664. æC  
  57665. CloseCPort releases the memory allocated to the cGrafPort. It disposes of the visRgn,
  57666. the clipRgn, the bkPixPat, the pnPixPat, the fillPixPat, and the grafVars handle. It
  57667. also disposes of the portPixMap, but doesn’t dispose of the portPixMap’s color table
  57668. (which is really owned by the gDevice). If you have placed your own color table into
  57669. the portPixMap, either dispose of it before calling CloseCPort, or store another
  57670. reference to it for other uses.
  57671.  
  57672. æKY NewPixMap
  57673. æFc Quickdraw.h
  57674. æT Function
  57675. æTN AA03
  57676. æD pascal PixMapHandle NewPixMap(void)
  57677.     = 0xAA03; 
  57678. æDT PixMapHandle myVariable = NewPixMap()(void);
  57679. æMM
  57680. æRI V-70
  57681. æC 
  57682. The NewPixMap function creates a new, initialized pixMap data structure and returns a
  57683. handle to it. All fields of the pixMap are copied from the current device’s pixMap
  57684. except the color table. A handle to the color table is allocated but not initialized.
  57685.  
  57686. æKY DisposPixMap
  57687. æFc Quickdraw.h
  57688. æT Function
  57689. æTN AA04
  57690. æD pascal void DisposPixMap(PixMapHandle pm)
  57691.     = 0xAA04; 
  57692. æDT DisposPixMap((PixMapHandle) pm);
  57693. æMM
  57694. æRI V-70
  57695. æC 
  57696. The DisposPixMap procedure releases all storage allocated by NewPixMap. It disposes
  57697. of the pixMap’s color table, and of the pixMap itself. Be careful not to dispose of a
  57698. pixMap whose color table is the same as the current device’s color table.
  57699.  
  57700. æKY CopyPixMap
  57701. æFc Quickdraw.h
  57702. æT Function
  57703. æTN AA05
  57704. æD pascal void CopyPixMap(PixMapHandle srcPM,PixMapHandle dstPM)
  57705.     = 0xAA05; 
  57706. æDT CopyPixMap((PixMapHandle) srcPM,(PixMapHandle) dstPM);
  57707. æRI V-70
  57708. æC  
  57709. The CopyPixMap routine is used for duplicating the pixMap data structure. CopyPixMap
  57710. copies the contents of the source pixMap data structure to the destination pixMap
  57711. data structure. The contents of the color table are copied, so the destination pixMap
  57712. has its own copy of the color table. Since the baseAddr field of the pixMap is a
  57713. pointer, the pointer, but not the image itself, is copied.
  57714.  
  57715. æKY NewPixPat
  57716. æFc Quickdraw.h
  57717. æT Function
  57718. æTN AA07
  57719. æD pascal PixPatHandle NewPixPat(void)
  57720.     = 0xAA07; 
  57721. æDT PixPatHandle myVariable = NewPixPat()(void);
  57722. æMM
  57723. æRI V-72
  57724. æC  
  57725. The NewPixPat function creates a new pixPat data structure, and returns a handle to
  57726. it. It calls NewPixMap to allocate and initialize the pattern’s pixMap to the same
  57727. settings as theGDevice^^.GDPMap, and it sets the type of the pixPat to be a color
  57728. pattern. The pat1Data field is initialized to a 50% gray pattern. New handles for
  57729. data, expanded data, expanded map, and color table are allocated but not initialized.
  57730. Including the pixPat itself, it allocates a total of six handles.  You will generally
  57731. not need to use this routine since the GetPixPat routine can be used to read in a
  57732. pattern from a resource file.
  57733.  
  57734. The sizes of the pixMap and pixPat handles are the size of their respective data
  57735. structures (see the type declarations in the “Summary” section). The other three
  57736. handles are initially small in size. Once the pattern is drawn, the size of the
  57737. expanded data is proportional to the size of the pattern data, but adjusted to the
  57738. depth of the screen. The color table size is the size of the record structure plus
  57739. eight bytes times the number of colors in the table.
  57740.  
  57741. To create a color pattern, use NewPixPat to allocate a new PixPatHandle. Set the
  57742. rowBytes, bounds, and pixelSize of the pattern’s pixMap to the dimensions of the
  57743. desired pattern. The rowBytes should be equal to (width of bounds)*pixelSize/8; it
  57744. need not be even. The width and height of the bounds must be a power of two. Each
  57745. scanline of the pattern must be at least one byte in length—that is, (width of bounds)*pixelSize
  57746. must be at least eight. Set the other fields in the pattern’s pixMap as described in
  57747. the section on the pixMap data structure.
  57748.  
  57749. Your application can explicitly specify the color corresponding to each pixel value
  57750. with the color table. The color table for the pattern must be placed in the pmTable
  57751. in the pixPat’s pixMap. Patterns may also contain colors that are relative to the
  57752. foreground and background at the time that they are drawn. Refer to the section on
  57753. the pixPat data structure for more information on relative patterns.
  57754.  
  57755. æKY DisposPixPat
  57756. æFc Quickdraw.h
  57757. æT Function
  57758. æTN AA08
  57759. æD pascal void DisposPixPat(PixPatHandle pp)
  57760.     = 0xAA08; 
  57761. æDT DisposPixPat((PixPatHandle) pp);
  57762. æMM
  57763. æRI V-73
  57764. æC  
  57765. The DisposPixPat procedure releases all storage allocated by NewPixPat. It disposes
  57766. of the pixPat’s data handle, expanded data handle, and pixMap handle.
  57767.  
  57768. æKY CopyPixPat
  57769. æFc Quickdraw.h
  57770. æT Function
  57771. æTN AA09
  57772. æD pascal void CopyPixPat(PixPatHandle srcPP,PixPatHandle dstPP)
  57773.     = 0xAA09; 
  57774. æDT CopyPixPat((PixPatHandle) srcPP,(PixPatHandle) dstPP);
  57775. æRI V-73
  57776. æC  
  57777. The CopyPixPat procedure copies the contents of the source pixPat to the destination
  57778. pixPat. It entirely copies all fields in the source pixPat, including the contents of
  57779. the data handle, expanded data handle, expanded map, pixMap handle, and color table.
  57780.  
  57781. æKY PenPixPat
  57782. æFc Quickdraw.h
  57783. æT Function
  57784. æTN AA0A
  57785. æD pascal void PenPixPat(PixPatHandle pp)
  57786.     = 0xAA0A; 
  57787. æDT PenPixPat((PixPatHandle) pp);
  57788. æMM
  57789. æRI V-74
  57790. æC 
  57791. The PenPixPat and BackPixPat calls are analogous to PenPat and BackPat, but use
  57792. multicolor pixel patterns instead of old-style patterns.  If you try to use a pixel
  57793. pattern in a grafPort, the data in the pat1Data field is placed into pnPat, bkPat, or
  57794. fillPat.
  57795.  
  57796. When your application sets a pixel pattern, the handle you provide is actually placed
  57797. into the grafPort or cGrafPort. In this way, QuickDraw can expand the pattern once
  57798. (saving it in the patXData field) when the pattern is first set, and won’t have to
  57799. reexpand it each time you set the pattern.
  57800.  
  57801. Since your handle is actually stored in the grafPort or cGrafPort, it’s considered
  57802. bad form to dispose of a PixPatHandle that is currently set as the pnPixPat or bkPixPat.
  57803. (Just in case you forget, QuickDraw will remove all references to your pattern from
  57804. existing grafPorts or cGrafPorts when you dispose of it.)
  57805.  
  57806. Using the old calls PenPat and BackPat, you can still set old-style patterns in a
  57807. cGrafPort. If necessary, it creates a new pixPatHandle in which to store the pattern
  57808. (because, as described above, pixPatHandles are owned by the application). As in old
  57809. grafPorts, old-style patterns are drawn using the foreground and background colors at
  57810. the time of drawing, not at the time the pattern is set.
  57811.  
  57812. æKY BackPixPat
  57813. æFc Quickdraw.h
  57814. æT Function
  57815. æTN AA0B
  57816. æD pascal void BackPixPat(PixPatHandle pp)
  57817.     = 0xAA0B; 
  57818. æDT BackPixPat((PixPatHandle) pp);
  57819. æMM
  57820. æRI V-74
  57821. æC  
  57822. The PenPixPat and BackPixPat calls are analogous to PenPat and BackPat, but use
  57823. multicolor pixel patterns instead of old-style patterns.  If you try to use a pixel
  57824. pattern in a grafPort, the data in the pat1Data field is placed into pnPat, bkPat, or
  57825. fillPat.
  57826.  
  57827. When your application sets a pixel pattern, the handle you provide is actually placed
  57828. into the grafPort or cGrafPort. In this way, QuickDraw can expand the pattern once
  57829. (saving it in the patXData field) when the pattern is first set, and won’t have to
  57830. reexpand it each time you set the pattern.
  57831.  
  57832. Since your handle is actually stored in the grafPort or cGrafPort, it’s considered
  57833. bad form to dispose of a PixPatHandle that is currently set as the pnPixPat or bkPixPat.
  57834. (Just in case you forget, QuickDraw will remove all references to your pattern from
  57835. existing grafPorts or cGrafPorts when you dispose of it.)
  57836.  
  57837. Using the old calls PenPat and BackPat, you can still set old-style patterns in a
  57838. cGrafPort. If necessary, it creates a new pixPatHandle in which to store the pattern
  57839. (because, as described above, pixPatHandles are owned by the application). As in old
  57840. grafPorts, old-style patterns are drawn using the foreground and background colors at
  57841. the time of drawing, not at the time the pattern is set.
  57842.  
  57843. æKY GetPixPat
  57844. æFc Quickdraw.h
  57845. æT Function
  57846. æTN AA0C
  57847. æD pascal PixPatHandle GetPixPat(short patID)
  57848.     = 0xAA0C; 
  57849. æDT PixPatHandle myVariable = GetPixPat((short) patID);
  57850. æMM
  57851. æRI V-73
  57852. æC  
  57853. The GetPixPat call creates a new pixPat data structure, and then uses the information
  57854. in the resource of type 'ppat' and the specified ID to initialize the pixPat. The
  57855. 'ppat' resource format is described in the section “Color QuickDraw Resource Formats”.
  57856. If the resource with the specified ID is not found, then this routine returns a NIL
  57857. handle.
  57858.  
  57859. æKY MakeRGBPat
  57860. æFc Quickdraw.h
  57861. æT Function
  57862. æTN AA0D
  57863. æD pascal void MakeRGBPat(PixPatHandle pp,const RGBColor *myColor)
  57864.     = 0xAA0D; 
  57865. æDT MakeRGBPat((PixPatHandle) pp,(const RGBColor *) myColor);
  57866. æRI V-73
  57867. æC  
  57868. The MakeRGBPat procedure is a new call which generates a pixPat that approximates the
  57869. specified color when drawn.  For example, if your application is drawing to a device
  57870. that has 4 bits per pixel, you will only get 16 colors if you simply set the foreground
  57871. color and draw. If you use MakeRGBPat to select a pattern, and then draw using that
  57872. pattern, you will effectively get 125 different colors. More colors are theoretically
  57873. possible; this implementation opted for a fast pattern selection rather than the best
  57874. possible pattern selection. If the device has 8 bits per pixel, you will effectively
  57875. get 2197 colors.
  57876.  
  57877. Note that these patterns aren’t usually solid; they provide a wide selection of
  57878. colors by alternating between colors with up to four colors in a pattern. For this
  57879. reason lines that are one pixel wide may not look good using these patterns. For an
  57880. RGB pattern, the patMap^^.bounds always contains (0, 0, 8, 8), and the patMap^^.rowbytes
  57881. equals 2. Figure 6 shows how these colors are arranged.
  57882.  
  57883. When MakeRGBPat creates a color table, it only fills in the last colorSpec field: the
  57884. other colorSpec values are computed at the time the drawing actually takes place,
  57885. using the current pixel depth for the system.
  57886.  
  57887.   Value    RGB
  57888.     0      computed RGB color
  57889.     1      computed RGB color
  57890.     2      computed RGB color
  57891.     3      computed RGB color
  57892.     4      RGBColor passed to MakeRGBPat routine
  57893.  
  57894. •••Refer to Figure 6.•••
  57895.  
  57896. Figure 6–RGB Pattern
  57897.  
  57898. æKY FillCRect
  57899. æFc Quickdraw.h
  57900. æT Function
  57901. æTN AA0E
  57902. æD pascal void FillCRect(const Rect *r,PixPatHandle pp)
  57903.     = 0xAA0E; 
  57904. æDT FillCRect((const Rect *) r,(PixPatHandle) pp);
  57905. æMM
  57906. æRI V-69
  57907. æC 
  57908. _______________________________________________________________________________
  57909.  
  57910. »Color Drawing Operations
  57911.  
  57912. PROCEDURE FillCRect (r: Rect; ppat: PixPatHandle);
  57913. PROCEDURE FillCOval (r: Rect; ppat: PixPatHandle);
  57914. PROCEDURE FillCRoundRect (r: Rect; ovWd,ovHt: INTEGER; ppat: PixPatHandle);
  57915. PROCEDURE FillCArc (r: Rect; startAngle,arcAngle: INTEGER; ppat: PixPatHandle);
  57916. PROCEDURE FillCRgn (rgn: RgnHandle; ppat: PixPatHandle);
  57917. PROCEDURE FillCPoly (poly: PolyHandle; ppat: PixPatHandle);
  57918.  
  57919. These calls are analogous to their similarly named counterparts in QuickDraw. They
  57920. allow a multicolored pattern to be used for filling.
  57921.  
  57922. æKY FillCOval
  57923. æFc Quickdraw.h
  57924. æT Function
  57925. æTN AA0F
  57926. æD pascal void FillCOval(const Rect *r,PixPatHandle pp)
  57927.     = 0xAA0F; 
  57928. æDT FillCOval((const Rect *) r,(PixPatHandle) pp);
  57929. æMM
  57930. æRI V-69
  57931. æC 
  57932. _______________________________________________________________________________
  57933.  
  57934. »Color Drawing Operations
  57935.  
  57936. PROCEDURE FillCRect (r: Rect; ppat: PixPatHandle);
  57937. PROCEDURE FillCOval (r: Rect; ppat: PixPatHandle);
  57938. PROCEDURE FillCRoundRect (r: Rect; ovWd,ovHt: INTEGER; ppat: PixPatHandle);
  57939. PROCEDURE FillCArc (r: Rect; startAngle,arcAngle: INTEGER; ppat: PixPatHandle);
  57940. PROCEDURE FillCRgn (rgn: RgnHandle; ppat: PixPatHandle);
  57941. PROCEDURE FillCPoly (poly: PolyHandle; ppat: PixPatHandle);
  57942.  
  57943. These calls are analogous to their similarly named counterparts in QuickDraw. They
  57944. allow a multicolored pattern to be used for filling.
  57945.  
  57946. æKY FillCRoundRect
  57947. æFc Quickdraw.h
  57948. æT Function
  57949. æTN AA10
  57950. æD pascal void FillCRoundRect(const Rect *r,short ovalWidth,short ovalHeight,
  57951.     PixPatHandle pp)
  57952.     = 0xAA10; 
  57953. æDT FillCRoundRect((const Rect *) r,(short) ovalWidth,(short) ovalHeight,()
  57954.     PixPatHandle pp);
  57955. æMM
  57956. æRI V-69
  57957. æC 
  57958. _______________________________________________________________________________
  57959.  
  57960. »Color Drawing Operations
  57961.  
  57962. PROCEDURE FillCRect (r: Rect; ppat: PixPatHandle);
  57963. PROCEDURE FillCOval (r: Rect; ppat: PixPatHandle);
  57964. PROCEDURE FillCRoundRect (r: Rect; ovWd,ovHt: INTEGER; ppat: PixPatHandle);
  57965. PROCEDURE FillCArc (r: Rect; startAngle,arcAngle: INTEGER; ppat: PixPatHandle);
  57966. PROCEDURE FillCRgn (rgn: RgnHandle; ppat: PixPatHandle);
  57967. PROCEDURE FillCPoly (poly: PolyHandle; ppat: PixPatHandle);
  57968.  
  57969. These calls are analogous to their similarly named counterparts in QuickDraw. They
  57970. allow a multicolored pattern to be used for filling.
  57971.  
  57972. æKY FillCArc
  57973. æFc Quickdraw.h
  57974. æT Function
  57975. æTN AA11
  57976. æD pascal void FillCArc(const Rect *r,short startAngle,short arcAngle,PixPatHandle pp)
  57977.     = 0xAA11; 
  57978. æDT FillCArc((const Rect *) r,(short) startAngle,(short) arcAngle,(PixPatHandle) pp);
  57979. æMM
  57980. æRI V-69
  57981. æC 
  57982. _______________________________________________________________________________
  57983.  
  57984. »Color Drawing Operations
  57985.  
  57986. PROCEDURE FillCRect (r: Rect; ppat: PixPatHandle);
  57987. PROCEDURE FillCOval (r: Rect; ppat: PixPatHandle);
  57988. PROCEDURE FillCRoundRect (r: Rect; ovWd,ovHt: INTEGER; ppat: PixPatHandle);
  57989. PROCEDURE FillCArc (r: Rect; startAngle,arcAngle: INTEGER; ppat: PixPatHandle);
  57990. PROCEDURE FillCRgn (rgn: RgnHandle; ppat: PixPatHandle);
  57991. PROCEDURE FillCPoly (poly: PolyHandle; ppat: PixPatHandle);
  57992.  
  57993. These calls are analogous to their similarly named counterparts in QuickDraw. They
  57994. allow a multicolored pattern to be used for filling.
  57995.  
  57996. æKY FillCRgn
  57997. æFc Quickdraw.h
  57998. æT Function
  57999. æTN AA12
  58000. æD pascal void FillCRgn(RgnHandle rgn,PixPatHandle pp)
  58001.     = 0xAA12; 
  58002. æDT FillCRgn((RgnHandle) rgn,(PixPatHandle) pp);
  58003. æMM
  58004. æRI V-69
  58005. æC 
  58006. _______________________________________________________________________________
  58007.  
  58008. »Color Drawing Operations
  58009.  
  58010. PROCEDURE FillCRect (r: Rect; ppat: PixPatHandle);
  58011. PROCEDURE FillCOval (r: Rect; ppat: PixPatHandle);
  58012. PROCEDURE FillCRoundRect (r: Rect; ovWd,ovHt: INTEGER; ppat: PixPatHandle);
  58013. PROCEDURE FillCArc (r: Rect; startAngle,arcAngle: INTEGER; ppat: PixPatHandle);
  58014. PROCEDURE FillCRgn (rgn: RgnHandle; ppat: PixPatHandle);
  58015. PROCEDURE FillCPoly (poly: PolyHandle; ppat: PixPatHandle);
  58016.  
  58017. These calls are analogous to their similarly named counterparts in QuickDraw. They
  58018. allow a multicolored pattern to be used for filling.
  58019.  
  58020. æKY FillCPoly
  58021. æFc Quickdraw.h
  58022. æT Function
  58023. æTN AA13
  58024. æD pascal void FillCPoly(PolyHandle poly,PixPatHandle pp)
  58025.     = 0xAA13; 
  58026. æDT FillCPoly((PolyHandle) poly,(PixPatHandle) pp);
  58027. æMM
  58028. æRI V-69
  58029. æC 
  58030. _______________________________________________________________________________
  58031.  
  58032. »Color Drawing Operations
  58033.  
  58034. PROCEDURE FillCRect (r: Rect; ppat: PixPatHandle);
  58035. PROCEDURE FillCOval (r: Rect; ppat: PixPatHandle);
  58036. PROCEDURE FillCRoundRect (r: Rect; ovWd,ovHt: INTEGER; ppat: PixPatHandle);
  58037. PROCEDURE FillCArc (r: Rect; startAngle,arcAngle: INTEGER; ppat: PixPatHandle);
  58038. PROCEDURE FillCRgn (rgn: RgnHandle; ppat: PixPatHandle);
  58039. PROCEDURE FillCPoly (poly: PolyHandle; ppat: PixPatHandle);
  58040.  
  58041. These calls are analogous to their similarly named counterparts in QuickDraw. They
  58042. allow a multicolored pattern to be used for filling.
  58043.  
  58044. æKY RGBForeColor
  58045. æFc Quickdraw.h
  58046. æT Function
  58047. æTN AA14
  58048. æD pascal void RGBForeColor(const RGBColor *color)
  58049.     = 0xAA14; 
  58050. æDT RGBForeColor((const RGBColor *) color);
  58051. æMM
  58052. æRI V-68
  58053. æC 
  58054. _______________________________________________________________________________
  58055.  
  58056. »Setting the Foreground and Background Colors
  58057.  
  58058. PROCEDURE RGBForeColor (color : RGBColor);
  58059. PROCEDURE RGBBackColor (color : RGBColor);
  58060.  
  58061. These two calls set the foreground and background colors to the best available match
  58062. for the current device. The only drawing operations that aren’t affected by these
  58063. colors are PlotCIcon, and drawing using the new color patterns. Before you call
  58064. CopyBits with a pixMap as the source, you should set the foreground to black and the
  58065. background to white.
  58066.  
  58067. If the current port is a cGrafPort, the specified RGB is placed in the rgbFgColor or
  58068. rgbBkColor field (and the pixel value most closely matching that color is placed in
  58069. the fgColor or bkColor field). If the current port is a grafPort, fgColor or bkColor
  58070. is set to the old QuickDraw color determined by taking the high bit of each of the R,
  58071. G, and B components, and using that three-bit number to select one of the eight
  58072. QuickDraw colors. The ordering of the QuickDraw colors is shown in the GetForeColor
  58073. description.
  58074.  
  58075. PROCEDURE GetForeColor (VAR color : RGBColor);
  58076. PROCEDURE GetBackColor (VAR color : RGBColor);
  58077.  
  58078. These two calls return the RGB components of the foreground and background colors set
  58079. in the current port. The calls work for both grafPorts and cGrafPorts. If the current
  58080. port is a cGrafPort, the returned value is taken directly from the rgbFgColor or
  58081. rgbBkColor field. If the current port is a grafPort, then only eight possible RGB
  58082. values can be returned. These eight values are determined by the values in a global
  58083. variable named QDColors, which is a pointer to a color table containing the current
  58084. QuickDraw colors.
  58085.  
  58086. The colors are stored in the following order:
  58087.  
  58088.   Value  Color      Red      Green    Blue
  58089.  
  58090.     0    black      $0000    $0000    $0000
  58091.     1    yellow     $FC00    $F37D    $052F
  58092.     2    magenta    $F2D7    $0856    $84EC
  58093.     3    red        $DD6B    $08C2    $06A2
  58094.     4    cyan       $0241    $AB54    $EAFF
  58095.     5    green      $0000    $8000    $11B0
  58096.     6    blue       $0000    $0000    $D400
  58097.     7    white      $FFFF    $FFFF    $FFFF
  58098.  
  58099. This is the set of colors that Color QuickDraw uses to determine precisely what
  58100. colors should be displayed by an old grafPort that is using color. The default set of
  58101. colors has been adjusted to match the colors produced on the ImageWriter II printer.
  58102.  
  58103. æKY RGBBackColor
  58104. æFc Quickdraw.h
  58105. æT Function
  58106. æTN AA15
  58107. æD pascal void RGBBackColor(const RGBColor *color)
  58108.     = 0xAA15; 
  58109. æDT RGBBackColor((const RGBColor *) color);
  58110. æMM
  58111. æRI V-68
  58112. æC 
  58113. _______________________________________________________________________________
  58114.  
  58115. »Setting the Foreground and Background Colors
  58116.  
  58117. PROCEDURE RGBForeColor (color : RGBColor);
  58118. PROCEDURE RGBBackColor (color : RGBColor);
  58119.  
  58120. These two calls set the foreground and background colors to the best available match
  58121. for the current device. The only drawing operations that aren’t affected by these
  58122. colors are PlotCIcon, and drawing using the new color patterns. Before you call
  58123. CopyBits with a pixMap as the source, you should set the foreground to black and the
  58124. background to white.
  58125.  
  58126. If the current port is a cGrafPort, the specified RGB is placed in the rgbFgColor or
  58127. rgbBkColor field (and the pixel value most closely matching that color is placed in
  58128. the fgColor or bkColor field). If the current port is a grafPort, fgColor or bkColor
  58129. is set to the old QuickDraw color determined by taking the high bit of each of the R,
  58130. G, and B components, and using that three-bit number to select one of the eight
  58131. QuickDraw colors. The ordering of the QuickDraw colors is shown in the GetForeColor
  58132. description.
  58133.  
  58134. PROCEDURE GetForeColor (VAR color : RGBColor);
  58135. PROCEDURE GetBackColor (VAR color : RGBColor);
  58136.  
  58137. These two calls return the RGB components of the foreground and background colors set
  58138. in the current port. The calls work for both grafPorts and cGrafPorts. If the current
  58139. port is a cGrafPort, the returned value is taken directly from the rgbFgColor or
  58140. rgbBkColor field. If the current port is a grafPort, then only eight possible RGB
  58141. values can be returned. These eight values are determined by the values in a global
  58142. variable named QDColors, which is a pointer to a color table containing the current
  58143. QuickDraw colors.
  58144.  
  58145. The colors are stored in the following order:
  58146.  
  58147.   Value  Color      Red      Green    Blue
  58148.  
  58149.     0    black      $0000    $0000    $0000
  58150.     1    yellow     $FC00    $F37D    $052F
  58151.     2    magenta    $F2D7    $0856    $84EC
  58152.     3    red        $DD6B    $08C2    $06A2
  58153.     4    cyan       $0241    $AB54    $EAFF
  58154.     5    green      $0000    $8000    $11B0
  58155.     6    blue       $0000    $0000    $D400
  58156.     7    white      $FFFF    $FFFF    $FFFF
  58157.  
  58158. This is the set of colors that Color QuickDraw uses to determine precisely what
  58159. colors should be displayed by an old grafPort that is using color. The default set of
  58160. colors has been adjusted to match the colors produced on the ImageWriter II printer.
  58161.  
  58162. æKY SetCPixel
  58163. æFc Quickdraw.h
  58164. æT Function
  58165. æTN AA16
  58166. æD pascal void SetCPixel(short h,short v,const RGBColor *cPix)
  58167.     = 0xAA16; 
  58168. æDT SetCPixel((short) h,(short) v,(const RGBColor *) cPix);
  58169. æMM
  58170. æRI V-70
  58171. æC  
  58172. The SetCPixel function sets the pixel at the specified position to the pixel value
  58173. that most closely matches the specified RGB.
  58174.  
  58175. æKY SetPortPix
  58176. æFc Quickdraw.h
  58177. æT Function
  58178. æTN AA06
  58179. æD pascal void SetPortPix(PixMapHandle pm)
  58180.     = 0xAA06; 
  58181. æDT SetPortPix((PixMapHandle) pm);
  58182. æRI V-76
  58183. æC  
  58184. The SetPortPix call is analogous to SetPortBits, and should be used instead of SetPortBits
  58185. for cGrafPorts. It replaces the portPixMap field of the current cGrafPort with the
  58186. specified handle. SetPortPix has no effect when used with an old grafPort. If SetPortBits
  58187. is called when the current port is a cGrafPort, it does nothing.
  58188.  
  58189. æKY GetCPixel
  58190. æFc Quickdraw.h
  58191. æT Function
  58192. æTN AA17
  58193. æD pascal void GetCPixel(short h,short v,RGBColor *cPix)
  58194.     = 0xAA17; 
  58195. æDT GetCPixel((short) h,(short) v,(RGBColor *) cPix);
  58196. æRI V-69
  58197. æC  
  58198. The GetCPixel function returns the RGB of the pixel at the specified position in the
  58199. current port.
  58200.  
  58201. æKY GetForeColor
  58202. æFc Quickdraw.h
  58203. æT Function
  58204. æTN AA19
  58205. æD pascal void GetForeColor(RGBColor *color)
  58206.     = 0xAA19; 
  58207. æDT GetForeColor((RGBColor *) color);
  58208. æRI V-68
  58209. æC 
  58210. _______________________________________________________________________________
  58211.  
  58212. »Setting the Foreground and Background Colors
  58213.  
  58214. PROCEDURE RGBForeColor (color : RGBColor);
  58215. PROCEDURE RGBBackColor (color : RGBColor);
  58216.  
  58217. These two calls set the foreground and background colors to the best available match
  58218. for the current device. The only drawing operations that aren’t affected by these
  58219. colors are PlotCIcon, and drawing using the new color patterns. Before you call
  58220. CopyBits with a pixMap as the source, you should set the foreground to black and the
  58221. background to white.
  58222.  
  58223. If the current port is a cGrafPort, the specified RGB is placed in the rgbFgColor or
  58224. rgbBkColor field (and the pixel value most closely matching that color is placed in
  58225. the fgColor or bkColor field). If the current port is a grafPort, fgColor or bkColor
  58226. is set to the old QuickDraw color determined by taking the high bit of each of the R,
  58227. G, and B components, and using that three-bit number to select one of the eight
  58228. QuickDraw colors. The ordering of the QuickDraw colors is shown in the GetForeColor
  58229. description.
  58230.  
  58231. PROCEDURE GetForeColor (VAR color : RGBColor);
  58232. PROCEDURE GetBackColor (VAR color : RGBColor);
  58233.  
  58234. These two calls return the RGB components of the foreground and background colors set
  58235. in the current port. The calls work for both grafPorts and cGrafPorts. If the current
  58236. port is a cGrafPort, the returned value is taken directly from the rgbFgColor or
  58237. rgbBkColor field. If the current port is a grafPort, then only eight possible RGB
  58238. values can be returned. These eight values are determined by the values in a global
  58239. variable named QDColors, which is a pointer to a color table containing the current
  58240. QuickDraw colors.
  58241.  
  58242. The colors are stored in the following order:
  58243.  
  58244.   Value  Color      Red      Green    Blue
  58245.  
  58246.     0    black      $0000    $0000    $0000
  58247.     1    yellow     $FC00    $F37D    $052F
  58248.     2    magenta    $F2D7    $0856    $84EC
  58249.     3    red        $DD6B    $08C2    $06A2
  58250.     4    cyan       $0241    $AB54    $EAFF
  58251.     5    green      $0000    $8000    $11B0
  58252.     6    blue       $0000    $0000    $D400
  58253.     7    white      $FFFF    $FFFF    $FFFF
  58254.  
  58255. This is the set of colors that Color QuickDraw uses to determine precisely what
  58256. colors should be displayed by an old grafPort that is using color. The default set of
  58257. colors has been adjusted to match the colors produced on the ImageWriter II printer.
  58258.  
  58259. æKY GetBackColor
  58260. æFc Quickdraw.h
  58261. æT Function
  58262. æTN AA1A
  58263. æD pascal void GetBackColor(RGBColor *color)
  58264.     = 0xAA1A; 
  58265. æDT GetBackColor((RGBColor *) color);
  58266. æRI V-68
  58267. æC  
  58268. _______________________________________________________________________________
  58269.  
  58270. »Setting the Foreground and Background Colors
  58271.  
  58272. PROCEDURE RGBForeColor (color : RGBColor);
  58273. PROCEDURE RGBBackColor (color : RGBColor);
  58274.  
  58275. These two calls set the foreground and background colors to the best available match
  58276. for the current device. The only drawing operations that aren’t affected by these
  58277. colors are PlotCIcon, and drawing using the new color patterns. Before you call
  58278. CopyBits with a pixMap as the source, you should set the foreground to black and the
  58279. background to white.
  58280.  
  58281. If the current port is a cGrafPort, the specified RGB is placed in the rgbFgColor or
  58282. rgbBkColor field (and the pixel value most closely matching that color is placed in
  58283. the fgColor or bkColor field). If the current port is a grafPort, fgColor or bkColor
  58284. is set to the old QuickDraw color determined by taking the high bit of each of the R,
  58285. G, and B components, and using that three-bit number to select one of the eight
  58286. QuickDraw colors. The ordering of the QuickDraw colors is shown in the GetForeColor
  58287. description.
  58288.  
  58289. PROCEDURE GetForeColor (VAR color : RGBColor);
  58290. PROCEDURE GetBackColor (VAR color : RGBColor);
  58291.  
  58292. These two calls return the RGB components of the foreground and background colors set
  58293. in the current port. The calls work for both grafPorts and cGrafPorts. If the current
  58294. port is a cGrafPort, the returned value is taken directly from the rgbFgColor or
  58295. rgbBkColor field. If the current port is a grafPort, then only eight possible RGB
  58296. values can be returned. These eight values are determined by the values in a global
  58297. variable named QDColors, which is a pointer to a color table containing the current
  58298. QuickDraw colors.
  58299.  
  58300. The colors are stored in the following order:
  58301.  
  58302.   Value  Color      Red      Green    Blue
  58303.  
  58304.     0    black      $0000    $0000    $0000
  58305.     1    yellow     $FC00    $F37D    $052F
  58306.     2    magenta    $F2D7    $0856    $84EC
  58307.     3    red        $DD6B    $08C2    $06A2
  58308.     4    cyan       $0241    $AB54    $EAFF
  58309.     5    green      $0000    $8000    $11B0
  58310.     6    blue       $0000    $0000    $D400
  58311.     7    white      $FFFF    $FFFF    $FFFF
  58312.  
  58313. This is the set of colors that Color QuickDraw uses to determine precisely what
  58314. colors should be displayed by an old grafPort that is using color. The default set of
  58315. colors has been adjusted to match the colors produced on the ImageWriter II printer.
  58316.  
  58317. æKY SeedCFill
  58318. æFc Quickdraw.h
  58319. æT Function
  58320. æTN AA50
  58321. æD pascal void SeedCFill(const BitMap *srcBits,const BitMap *dstBits,const Rect *srcRect,
  58322.     const Rect *dstRect,short seedH,short seedV,ColorSearchProcPtr matchProc,
  58323.     long matchData)
  58324.     = 0xAA50; 
  58325. æDT SeedCFill((const BitMap *) srcBits,(const BitMap *) dstBits,(const Rect *) srcRect,(
  58326.     const Rect) * dstRect,(short) seedH,(short) seedV,(ColorSearchProcPtr) matchProc,()
  58327.     long matchData);
  58328. æRI V-71
  58329. æC  
  58330. The SeedCFill procedure generates a mask for use with CopyMask or CopyBits, with bits
  58331. equal to 1 only in those positions where paint can leak from the starting seed point,
  58332. like the MacPaint® bucket tool.
  58333.  
  58334. Given a rectangle within a source bitMap or pixMap (srcBits), SeedCFill returns a
  58335. mask (dstBits) that contains 1’s in place of all pixels to which paint can leak from
  58336. the specified seed position (seedH, seedV), expressed in the local coordinate system
  58337. of the source pixMap. By default, paint can leak to all adjacent pixels whose RGB
  58338. value exactly match that of the seed. To use this default, set matchProc and matchData
  58339. to zero.
  58340.  
  58341. In generating the mask, SeedCFill performs CopyBits to convert srcBits to a
  58342. one-bit mask. It installs a default searchProc into the gDevice that returns 0 if the
  58343. RGB value matches that of the seed; all other RGB values return 1’s.
  58344.  
  58345. If you want to customize SeedCFill, your application can specify a matchProc that is
  58346. used instead of the default searchProc. It should return 0’s for RGB values that you
  58347. want to be filled, and 1’s for values that shouldn’t be filled. When the matchProc is
  58348. called, the GDRefCon field of the current gDevice contains a pointer to a record
  58349. having the following structure:
  58350.  
  58351. MatchRec = RECORD
  58352.              red:          INTEGER;
  58353.              green:        INTEGER;
  58354.              blue:         INTEGER;
  58355.              matchData:    LONGINT
  58356.            END;
  58357.  
  58358. In this record the red, green, and blue fields are the RGB of the pixel at the specified
  58359. seed location. MatchData is simply whatever value you passed to SeedCFill as a parameter.
  58360. For instance, your application could pass a handle to a color table whose entries
  58361. should all be filled, and then, in the matchProc, check to see if the specified RGB
  58362. matches any of the colors in the table.
  58363.  
  58364. No automatic scaling is performed: the source and destination rectangles must be the
  58365. same size. Calls to SeedCFill are not clipped to the current port and are not stored
  58366. into QuickDraw pictures.
  58367.  
  58368. æKY CalcCMask
  58369. æFc Quickdraw.h
  58370. æT Function
  58371. æTN AA4F
  58372. æD pascal void CalcCMask(const BitMap *srcBits,const BitMap *dstBits,const Rect *srcRect,
  58373.     const Rect *dstRect,const RGBColor *seedRGB,ColorSearchProcPtr matchProc,
  58374.     long matchData)
  58375.     = 0xAA4F; 
  58376. æDT CalcCMask((const BitMap *) srcBits,(const BitMap *) dstBits,(const Rect *) srcRect,(
  58377.     const Rect) * dstRect,(const RGBColor *) seedRGB,(ColorSearchProcPtr) matchProc,()
  58378.     long matchData);
  58379. æRI V-72
  58380. æC  
  58381. This routine generates a mask (dstBits) corresponding to the area in a pixMap
  58382. (srcBits) to which paint cannot leak from outside of the srcRect. The size of srcRect
  58383. must be the same as the size of dstRect.  By default, paint can leak to all adjacent
  58384. pixels whose RGB values don’t match that of the seedRGB. To use this default, set
  58385. matchProc and matchData to 0.
  58386.  
  58387. For instance, if srcBits contains a blue rectangle on a red background, and your
  58388. application calls CalcCMask with the seedRGB equal to blue, then the returned mask
  58389. has ones in the positions corresponding to the edges and interior of the rectangle,
  58390. and zeros outside of the rectangle.
  58391.  
  58392. If you want to customize CalcCMask, your application can specify a matchProc that is
  58393. used instead of the default searchProc. It should return 1’s for RGB values that
  58394. define the edges of the mask, and 0’s for values that don’t.
  58395.  
  58396. When the matchProc is called, the GDRefCon field of the gDevice contains a pointer to
  58397. a MatchRec record (the structure shown in the SeedCFill description). The red, green,
  58398. and blue fields are the RGB of the pixel at the specifed seed location. MatchData is
  58399. simply whatever value your application passed to CalcCMask as a parameter. For instance,
  58400. your program could pass a handle to a color table whose entries should all be within
  58401. the mask, and then, in the matchProc, check to see if the specified RGB matches any
  58402. of the colors in the table.
  58403.  
  58404. No automatic scaling is performed: the source and destination rectangles must be the
  58405. same size. Calls to CalcCMask are not clipped to the current port and are not stored
  58406. into QuickDraw pictures.
  58407.  
  58408. æKY OpColor
  58409. æFc Quickdraw.h
  58410. æT Function
  58411. æTN AA21
  58412. æD pascal void OpColor(const RGBColor *color)
  58413.     = 0xAA21; 
  58414. æDT OpColor((const RGBColor *) color);
  58415. æRI V-77
  58416. æC 
  58417. If the current port is a cGrafPort, the OpColor procedure sets the red, green, and
  58418. blue values used by the AddPin, SubPin, and Blend drawing modes. This information is
  58419. actually stored in the grafVars handle in the cGrafPort, but you should never need to
  58420. reference it directly. If the current port is a grafPort, OpColor has no effect.
  58421.  
  58422. æKY HiliteColor
  58423. æFc Quickdraw.h
  58424. æT Function
  58425. æTN AA22
  58426. æD pascal void HiliteColor(const RGBColor *color)
  58427.     = 0xAA22; 
  58428. æDT HiliteColor((const RGBColor *) color);
  58429. æRI V-77
  58430. æC  
  58431. The highlight color is used by all drawing operations that use the highlight transfer
  58432. mode. When a cGrafPort is created, its highlight color is initialized from the global
  58433. variable HiliteRGB.  The HiliteColor procedure allows you to change the highlighting
  58434. color used by the current port. This information is actually stored in the grafVars
  58435. handle in the cGrafPort, but you should never need to reference it directly. If the
  58436. current port is a grafPort, HiliteColor has no effect.
  58437.  
  58438. æKY DisposCTable
  58439. æFc Quickdraw.h
  58440. æT Function
  58441. æTN AA24
  58442. æD pascal void DisposCTable(CTabHandle cTable)
  58443.     = 0xAA24; 
  58444. æDT DisposCTable((CTabHandle) cTable);
  58445. æMM
  58446. æRI V-78
  58447. æC  
  58448. The DisposCTable procedure disposes the handle allocated for a color table.
  58449.  
  58450. æKY GetCTable
  58451. æFc Quickdraw.h
  58452. æT Function
  58453. æTN AA18
  58454. æD pascal CTabHandle GetCTable(short ctID)
  58455.     = 0xAA18; 
  58456. æDT CTabHandle myVariable = GetCTable((short) ctID);
  58457. æMM
  58458. æRI V-77
  58459. æC  
  58460. The GetCTable routine allocates a new color table data structure, and initializes it
  58461. using the information in the resource of type 'clut' having the specified ID.  If the
  58462. specified resource is not found, a NIL handle is returned.
  58463.  
  58464. If you place this handle into a pixMap, you should first dispose of the handle that
  58465. was already there.
  58466.  
  58467. The format of the 'clut' resource is given in the section “Color QuickDraw Resource
  58468. Formats”.  Resource ID values 0..127 are reserved for system use. Any
  58469. 'clut' resources defined by your application should have IDs in the range
  58470. 128..1023. This value must be in the ctSeed field in the resource, and will be placed
  58471. in the ctSeed field of the color table (for color table identification). All other
  58472. possible seed values are used to identify newly created color tables, and color
  58473. tables that have been modified.
  58474.  
  58475. If you modify a color table, you should invalidate it by changing its ctSeed field.
  58476. You can get a new unique value for ctSeed using the routine GetCTSeed, described in
  58477. the Color Manager chapter.
  58478.  
  58479. æKY GetCCursor
  58480. æFc Quickdraw.h
  58481. æT Function
  58482. æTN AA1B
  58483. æD pascal CCrsrHandle GetCCursor(short crsrID)
  58484.     = 0xAA1B; 
  58485. æDT CCrsrHandle myVariable = GetCCursor((short) crsrID);
  58486. æMM
  58487. æRI V-75, P-88, 171
  58488. æC 
  58489. The GetCCursor call creates a new CCrsr data structure, then initializes it using the
  58490. information in the resource of type 'crsr' with the specified ID. The 'crsr' resource
  58491. format is described in the section “Color QuickDraw Resource Formats”. If the resource
  58492. with the specified ID isn’t found, then this routine returns a NIL handle.
  58493.  
  58494. Since GetCCursor creates a new CCrsr data structure each time it is called, your
  58495. application shouldn’t call GetCCursor before each call to SetCCursor
  58496. (unlike the way GetCursor/SetCursor were normally used).  GetCCursor doesn’t dispose
  58497. or detach the resource, so resources of type 'crsr' should typically be purgeable.
  58498.  
  58499. æKY SetCCursor
  58500. æFc Quickdraw.h
  58501. æT Function
  58502. æTN AA1C
  58503. æD pascal void SetCCursor(CCrsrHandle cCrsr)
  58504.     = 0xAA1C; 
  58505. æDT SetCCursor((CCrsrHandle) cCrsr);
  58506. æMM
  58507. æRI V-75, P-88, 179
  58508. æC  
  58509. The SetCCursor procedure allows your application to set a multicolor cursor.  At the
  58510. time the cursor is set, it’s expanded to the current screen depth so that it can be
  58511. drawn rapidly.
  58512.  
  58513. If your application has changed the cursor’s data or its color table, it must also
  58514. invalidate the fields crsrXValid and crsrID (described in the section on the Color
  58515. Cursor data structure), before calling SetCCursor.
  58516.  
  58517. æKY AllocCursor
  58518. æFc Quickdraw.h
  58519. æT Function
  58520. æTN AA1D
  58521. æD pascal void AllocCursor(void)
  58522.     = 0xAA1D; 
  58523. æDT AllocCursor()(void);
  58524. æRI V-75
  58525. æC  
  58526. The AllocCursor procedure reallocates cursor memory. Under normal circumstances, you
  58527. should never need to use this call, since reallocation of cursor memory is only
  58528. necessary after the depth of one of the screens has been changed.
  58529.  
  58530. æKY DisposCCursor
  58531. æFc Quickdraw.h
  58532. æT Function
  58533. æTN AA26
  58534. æD pascal void DisposCCursor(CCrsrHandle cCrsr)
  58535.     = 0xAA26; 
  58536. æDT DisposCCursor((CCrsrHandle) cCrsr);
  58537. æRI V-75
  58538. æC  
  58539. The DisposCCursor procedure disposes all structures allocated by GetCCursor.
  58540.  
  58541. æKY GetCIcon
  58542. æFc Quickdraw.h
  58543. æT Function
  58544. æTN AA1E
  58545. æD pascal CIconHandle GetCIcon(short iconID)
  58546.     = 0xAA1E; 
  58547. æDT CIconHandle myVariable = GetCIcon((short) iconID);
  58548. æMM
  58549. æRI V-76
  58550. æC  
  58551. The GetCIcon function allocates a CIcon data structure and initializes it using the
  58552. information in the resource of type 'cicn' with the specified ID. It returns the
  58553. handle to the icon’s data structure. If the specified resource
  58554. isn’t found, a NIL handle is returned.
  58555.  
  58556. The format of the 'cicn' resource is described in the section “Color QuickDraw Resource
  58557. Formats”.
  58558.  
  58559. Since GetCIcon creates a new CIcon data structure each time it is called, your application
  58560. shouldn’t call GetCIcon before each call to PlotCIcon. GetCIcon doesn’t dispose or
  58561. detach the resource, so resources of type 'cicn' should typically be purgeable.
  58562.  
  58563. æKY PlotCIcon
  58564. æFc Quickdraw.h
  58565. æT Function
  58566. æTN AA1F
  58567. æD pascal void PlotCIcon(const Rect *theRect,CIconHandle theIcon)
  58568.     = 0xAA1F; 
  58569. æDT PlotCIcon((const Rect *) theRect,(CIconHandle) theIcon);
  58570. æMM
  58571. æRI V-76
  58572. æC  
  58573. The PlotCIcon procedure draws the specified icon in the specified rectangle. The
  58574. iconMask field of the CIcon determines which pixels of the iconPMap are drawn and
  58575. which are not. Only pixels with 1’s in corresponding positions in the iconMask are
  58576. drawn; all other pixels don’t affect the destination. If the screen depth is one or
  58577. two bits per pixel, the iconBMap is used as the source instead of the iconPMap (unless
  58578. the rowBytes field of iconBMap is 0, indicating that there is no iconBMap.
  58579.  
  58580. When the icon is drawn, the boundsRect of the iconPMap is used as the image’s source
  58581. rectangle. The icon and its mask are both stretched to the destination rectangle. The
  58582. icon’s pixels are remapped to the current depth and color table, if necessary. The
  58583. bounds fields of the iconPMap, iconBMap, and iconMask are expected to be equal in
  58584. size.
  58585.  
  58586. PlotCIcon is simply a structured call to CopyMask. As such, it doesn’t send any of
  58587. its drawing commands through grafProc routines; thus, PlotCIcon calls are not recorded
  58588. in pictures.
  58589.  
  58590. æKY DisposCIcon
  58591. æFc Quickdraw.h
  58592. æT Function
  58593. æTN AA25
  58594. æD pascal void DisposCIcon(CIconHandle theIcon)
  58595.     = 0xAA25; 
  58596. æDT DisposCIcon((CIconHandle) theIcon);
  58597. æMM
  58598. æRI V-76
  58599. æC  
  58600. The DisposCIcon procedure disposes all structures allocated by GetCIcon.
  58601.  
  58602. æKY SetStdCProcs
  58603. æFc Quickdraw.h
  58604. æT Function
  58605. æTN AA4E
  58606. æD pascal void SetStdCProcs(CQDProcs *procs)
  58607.     = 0xAA4E; 
  58608. æDT SetStdCProcs((CQDProcs *) procs);
  58609. æRI V-77
  58610. æC  
  58611. This procedure sets all the fields of the given CQDProcs record to point to the
  58612. standard low-level routines. You can then change the ones you wish to point to your
  58613. own routines. For example, if your procedure that processes picture comments is named
  58614. MyComments, you will store @MyComments in the commentProc field of the CQD Procs
  58615. record.
  58616.  
  58617. When drawing in a cGrafPort, your application must always use SetStdCProcs instead of
  58618. SetStdProcs.
  58619.  
  58620. æKY CharExtra
  58621. æFc Quickdraw.h
  58622. æT Function
  58623. æTN AA23
  58624. æD pascal void CharExtra(Fixed extra)
  58625.     = 0xAA23; 
  58626. æDT CharExtra((Fixed) extra);
  58627. æRI V-77
  58628. æC  
  58629. The CharExtra procedure sets the cGrafPort’s charExtra field, which specifies the
  58630. number of pixels by which to widen every character excluding the space character in a
  58631. line of text. The charExtra field is stored in a compressed format based on the
  58632. txSize field, so you must set txSize before calling CharExtra. The initial charExtra
  58633. setting is 0. CharExtra will accept a negative number. CharExtra has no effect on
  58634. grafPorts.
  58635.  
  58636. æKY GetMaxDevice
  58637. æFc Quickdraw.h
  58638. æT Function
  58639. æTN AA27
  58640. æD pascal GDHandle GetMaxDevice(const Rect *globalRect)
  58641.     = 0xAA27; 
  58642. æDT GDHandle myVariable = GetMaxDevice((const Rect *) globalRect);
  58643. æRI V-125
  58644. æC 
  58645. The GetMaxDevice routine returns a handle to the deepest device that intersects the
  58646. specified global rectangle. Your application might use this routine to allocate
  58647. offscreen pixMaps, as described in the following section.
  58648.  
  58649. æKY GetCTSeed
  58650. æFc Quickdraw.h
  58651. æT Function
  58652. æTN AA28
  58653. æD pascal long GetCTSeed(void)
  58654.     = 0xAA28; 
  58655. æDT long myVariable = GetCTSeed()(void);
  58656. æRI V-143
  58657. æC     
  58658. The GetCTSeed function returns a unique seed value that can be used in the ctSeed
  58659. field of a color table created by an application. This seed value guarantees that the
  58660. color table will be recognized as distinct from the destination, and that color table
  58661. translation will be performed properly. The return value will be greater than the
  58662. value stored in minSeed.
  58663.  
  58664. æKY GetDeviceList
  58665. æFc Quickdraw.h
  58666. æT Function
  58667. æTN AA29
  58668. æD pascal GDHandle GetDeviceList(void)
  58669.     = 0xAA29; 
  58670. æDT GDHandle myVariable = GetDeviceList()(void);
  58671. æRI V-124
  58672. æC     
  58673. The GetDeviceList function returns a handle to the first device in the DeviceList.
  58674.  
  58675. Assembly-language note:  A handle to the first element in the device
  58676.                          list is kept in the global variable DeviceList.
  58677.  
  58678. æKY GetMainDevice
  58679. æFc Quickdraw.h
  58680. æT Function
  58681. æTN AA2A
  58682. æD pascal GDHandle GetMainDevice(void)
  58683.     = 0xAA2A; 
  58684. æDT GDHandle myVariable = GetMainDevice()(void);
  58685. æRI V-124
  58686. æC  
  58687. The GetMainDevice function returns the handle of the gDevice that has the menu bar on
  58688. it.  Your application can examine this gDevice to determine the size or depth of the
  58689. main screen.
  58690.  
  58691. Assembly-language note:  A handle to the current main device is kept
  58692.                          in the global variable MainDevice.
  58693.  
  58694. æKY GetNextDevice
  58695. æFc Quickdraw.h
  58696. æT Function
  58697. æTN AA2B
  58698. æD pascal GDHandle GetNextDevice(GDHandle curDevice)
  58699.     = 0xAA2B; 
  58700. æDT GDHandle myVariable = GetNextDevice((GDHandle) curDevice);
  58701. æRI V-124
  58702. æC 
  58703. The GetnextDevice function returns the handle of the next gDevice in the DeviceList. 
  58704. If there are no more devices in the list, it returns NIL.
  58705.  
  58706. æKY TestDeviceAttribute
  58707. æFc Quickdraw.h
  58708. æT Function
  58709. æTN AA2C
  58710. æD pascal Boolean TestDeviceAttribute(GDHandle gdh,short attribute)
  58711.     = 0xAA2C; 
  58712. æDT Boolean myVariable = TestDeviceAttribute((GDHandle) gdh,(short) attribute);
  58713. æRI V-124
  58714. æC  
  58715. The TestDeviceAttribute function tests a single attribute to see if it is true or
  58716. not.  If your application is scanning through the device list, it would typically use
  58717. this routine to test if a device is a screen device, and if so, test to see if it’s
  58718. active. Then your application can draw to any active screen devices.
  58719.  
  58720. æKY SetDeviceAttribute
  58721. æFc Quickdraw.h
  58722. æT Function
  58723. æTN AA2D
  58724. æD pascal void SetDeviceAttribute(GDHandle gdh,short attribute,Boolean value)
  58725.     = 0xAA2D; 
  58726. æDT SetDeviceAttribute((GDHandle) gdh,(short) attribute,(Boolean) value);
  58727. æRI V-124
  58728. æC  
  58729. The SetDeviceAttribute routine can be used to set a device’s attribute bits. The
  58730. following attributes may be set using this call:
  58731.  
  58732. gdDevType     = 0;   {0 = monochrome, 1 = color}
  58733. ramInit       = 10;  {set if device has been initialized from RAM}
  58734. mainScreen    = 11;  {set if device is main screen}
  58735. allInit       = 12;  {set if devices were initialized from a 'scrn' resource}
  58736. screenDevice  = 13;  {set if device is a screen device}
  58737. noDriver      = 14;  {set if device has no driver}
  58738. screenActive  = 15;  {set if device is active}
  58739.  
  58740. æKY InitGDevice
  58741. æFc Quickdraw.h
  58742. æT Function
  58743. æTN AA2E
  58744. æD pascal void InitGDevice(short qdRefNum,long mode,GDHandle gdh)
  58745.     = 0xAA2E; 
  58746. æDT InitGDevice((short) qdRefNum,(long) mode,(GDHandle) gdh);
  58747. æMM
  58748. æRI V-122
  58749. æC  
  58750. The InitGDevice routine sets the video device whose driver has the specified gdRefNum
  58751. to the specified mode. It then fills out the gDevice record structure specified by
  58752. the gdh parameter to contain all information describing that mode. The GDHandle
  58753. should have been allocated by a call to NewGDevice.
  58754.  
  58755. The mode determines the configuration of the device;  possible modes for a device can
  58756. be determined by interrogating the video card’s ROM via calls to the Slot Manager
  58757. (refer to the Slot Manager chapter and the Designing Cards and Drivers manual). 
  58758. Refer to the Device Manager chapter for more details about the interaction of devices
  58759. and their drivers.
  58760.  
  58761. The information describing the new mode is primarily contained in the video card’s
  58762. ROM.  If the device has a fixed color table, then that table is read directly from
  58763. the ROM.  If the device has a variable color table, then the default color table for
  58764. that depth is used (the 'clut' resource with ID=depth).
  58765.  
  58766. In general, your application should never need to call this routine.  All video
  58767. devices are initialized at start time and their modes are changed by the control
  58768. panel.  If your program is initializing a device without a driver, this call will do
  58769. nothing; your application must initialize all fields of the gDevice.  It is worth
  58770. noting that after your program initializes the color table for the device, it needs
  58771. to call MakeITable to build the inverse table for the device.
  58772.  
  58773. æKY NewGDevice
  58774. æFc Quickdraw.h
  58775. æT Function
  58776. æTN AA2F
  58777. æD pascal GDHandle NewGDevice(short refNum,long mode)
  58778.     = 0xAA2F; 
  58779. æDT GDHandle myVariable = NewGDevice((short) refNum,(long) mode);
  58780. æMM
  58781. æRI V-122
  58782. æC  
  58783. The NewGDevice function allocates a new gDevice data structure and all of its handles,
  58784. then calls InitGDevice to initialize it for the specified device in the specified
  58785. mode.  If the request is unsuccessful, a NIL handle is returned.  The new gDevice and
  58786. all of its handles are allocated in the system heap. All attributes in the GDFlags
  58787. word are set to FALSE.
  58788.  
  58789. If your application creates a gDevice without a driver, the mode parameter should be
  58790. set to –1.  In this case, InitGDevice is not called to initialize the gDevice.  Your
  58791. application must perform all initialization.
  58792.  
  58793. A graphics device’s default mode is defined as 128, as described in the Designing
  58794. Cards and Drivers manual; this is assumed to be a monochrome mode. If the mode parameter
  58795. is not the default mode, the gdDevType attribute is set TRUE, to indicate that the
  58796. device is capable of displaying color (see the SetDeviceAttribute call).
  58797.  
  58798. This routine doesn’t automatically insert the gDevice into the device list.  In
  58799. general, your application shouldn’t add devices that it created to the device list.
  58800.  
  58801. æKY DisposGDevice
  58802. æFc Quickdraw.h
  58803. æT Function
  58804. æTN AA30
  58805. æD pascal void DisposGDevice(GDHandle gdh)
  58806.     = 0xAA30; 
  58807. æDT DisposGDevice((GDHandle) gdh);
  58808. æMM
  58809. æRI V-123
  58810. æC  
  58811. The DisposGDevice function disposes of the current gDevice and releases the space
  58812. allocated for it, and all data structures allocated by NewGDevice.
  58813.  
  58814. æKY SetGDevice
  58815. æFc Quickdraw.h
  58816. æT Function
  58817. æTN AA31
  58818. æD pascal void SetGDevice(GDHandle gd)
  58819.     = 0xAA31; 
  58820. æDT SetGDevice((GDHandle) gd);
  58821. æRI V-123
  58822. æC  
  58823. The SetGDevice procedure sets the specified gDevice as the current device.  Your
  58824. application won’t generally need to use this call except to draw to offscreen gDevices.
  58825.  
  58826. æKY GetGDevice
  58827. æFc Quickdraw.h
  58828. æT Function
  58829. æTN AA32
  58830. æD pascal GDHandle GetGDevice(void)
  58831.     = 0xAA32; 
  58832. æDT GDHandle myVariable = GetGDevice()(void);
  58833. æRI V-123
  58834. æC 
  58835. The GetGDevice routine returns a handle to the current gDevice.  This is useful for
  58836. determining the characteristics of the current output device (for instance its pixelSize
  58837. or color table).  Note that since a window can span screen boundaries, this call does
  58838. not return the device that describes a port.
  58839.  
  58840. Assembly-language note:  A handle to the currently active device is kept
  58841.                          in the global variable TheGDevice.
  58842.  
  58843. æKY Color2Index
  58844. æFc Quickdraw.h
  58845. æT Function
  58846. æTN AA33
  58847. æD pascal long Color2Index(const RGBColor *myColor)
  58848.     = 0xAA33; 
  58849. æDT long myVariable = Color2Index((const RGBColor *) myColor);
  58850. æMM
  58851. æRI V-141
  58852. æC  
  58853. The Color2Index routine finds the best available approximation to a given absolute
  58854. color, using the list of search procedures in the current device record. It returns a
  58855. longint, which is a pixel value padded with zeros in the high word. Since the colorSpec.value
  58856. field is only a word, the result returned from Color2Index must be truncated to fit
  58857. into a colorSpec. In pixMaps the.value is the low-order word of this index.
  58858.  
  58859. Color2Index shouldn’t be called from a custom search procedure.
  58860.  
  58861. æKY Index2Color
  58862. æFc Quickdraw.h
  58863. æT Function
  58864. æTN AA34
  58865. æD pascal void Index2Color(long index,RGBColor *aColor)
  58866.     = 0xAA34; 
  58867. æDT Index2Color((long) index,(RGBColor *) aColor);
  58868. æRI V-141
  58869. æC  
  58870. The Index2Color routine finds the RGB color corresponding to a given color table
  58871. index. The desired pixel value is passed and the corresponding RGB value is returned
  58872. in RGB. The routine takes a longint, which should be a pixel value padded with zeros
  58873. in the high word (normally the compiler does this automatically). Normally, the RGB
  58874. from the current device color table corresponding to the index is returned as the
  58875. RGBColor. Notice that this is not necessarily the same color that was originally
  58876. requested via RGBForeColor, RGBBackColor, SetCPixel, or Color2Index. This RGB is read
  58877. from the current gDevice color table.
  58878.  
  58879. æKY InvertColor
  58880. æFc Quickdraw.h
  58881. æT Function
  58882. æTN AA35
  58883. æD pascal void InvertColor(RGBColor *myColor)
  58884.     = 0xAA35; 
  58885. æDT InvertColor((RGBColor *) myColor);
  58886. æRI V-141
  58887. æC  
  58888. The InvertColor routine finds the complement of an absolute color, using the list of
  58889. complement procedures in the current device record. The default complement procedure
  58890. uses the 1’s complement of each component of the requested color.
  58891.  
  58892. æKY RealColor
  58893. æFc Quickdraw.h
  58894. æT Function
  58895. æTN AA36
  58896. æD pascal Boolean RealColor(const RGBColor *color)
  58897.     = 0xAA36; 
  58898. æDT Boolean myVariable = RealColor((const RGBColor *) color);
  58899. æMM
  58900. æRI V-141
  58901. æC 
  58902. The RealColor routine tells whether a given absolute color actually exists in the
  58903. current device’s color table. This decision is based on the current resolution of the
  58904. inverse table. For example, if the current iTabRes is four, RealColor returns TRUE if
  58905. there exists a color that exactly matches the top four bits of red, green, and blue.
  58906.  
  58907. æKY GetSubTable
  58908. æFc Quickdraw.h
  58909. æT Function
  58910. æTN AA37
  58911. æD pascal void GetSubTable(CTabHandle myColors,short iTabRes,CTabHandle targetTbl)
  58912.     = 0xAA37; 
  58913. æDT GetSubTable((CTabHandle) myColors,(short) iTabRes,(CTabHandle) targetTbl);
  58914. æMM
  58915. æRI V-142
  58916. æC  
  58917. The GetSubTable routine takes a ColorTable pointed at by myColors, and maps each RGB
  58918. value into its nearest available match for each target table. These best matches are
  58919. returned in the colorSpec.value fields of myColors. The values returned are best
  58920. matches to the RGBColor in targetTbl and the returned indices are indices into targetTbl.
  58921. Best matches are calculated using Color2Index and all applicable rules apply. A
  58922. temporary inverse table is built, and then discarded. ITabRes controls the resolution
  58923. of the iTable that is built. If targetTbl is NIL, then the current device’s color
  58924. table is used, and the
  58925. device’s inverse table is used rather than building a new one. To provide a different
  58926. resolution than the current inverse table, provide an explicit targetTbl parameter;
  58927. don’t pass a NIL parameter.
  58928.  
  58929. Warning:  Depending on the requested resolution, building the inverse table
  58930.           can require large amounts of temporary space in the application
  58931.           heap:  twice the size of the table itself, plus a fixed overhead
  58932.           for each inverse table resolution of 3–15K bytes.
  58933.  
  58934. æKY MakeITable
  58935. æFc Quickdraw.h
  58936. æT Function
  58937. æTN AA39
  58938. æD pascal void MakeITable(CTabHandle cTabH,ITabHandle iTabH,short res)
  58939.     = 0xAA39; 
  58940. æDT MakeITable((CTabHandle) cTabH,(ITabHandle) iTabH,(short) res);
  58941. æMM
  58942. æRI V-142
  58943. æC  
  58944. The MakeITable routine generates an inverse table based on the current contents of
  58945. the color table pointed to by CTabHandle, with a resolution of res bits per channel.
  58946. Reserved color table pixel values are not included in the resultant color table.
  58947. MakeITable tests its input parameters and will return an error in QDError if the
  58948. resolution is less than three or greater than five. Passing a NIL parameter to CTabHandle
  58949. or ITabHandle substitutes an appropriate handle from the current gDevice, while
  58950. passing 0 for res substitutes the current gDevice’s preferred table resolution. These
  58951. defaults can be used in any combination with explicit values, or with NIL parameters.
  58952.  
  58953. This routine allows maximum precision in matching colors, even if colors in the color
  58954. table differ by less than the resolution of the inverse table. Five-bit inverse
  58955. tables are not needed when drawing in normal QuickDraw modes. However, the new QuickDraw
  58956. transfer modes (add, subtract, blend, etc.) may require a
  58957. 5-bit inverse table for best results with certain color tables. MakeITable returns a
  58958. QDError if the destination inverse table memory cannot be allocated. The 'mitq'
  58959. resource governs how much memory is allocated for temporary internal structures; this
  58960. resource type is for internal use only.
  58961.  
  58962. Warning:  Depending on the requested resolution, building the inverse table
  58963.           can require large amounts of temporary space in the application
  58964.           heap:  twice the size of the table itself, plus a fixed overhead
  58965.           for each inverse table resolution of 3–15K bytes.
  58966.  
  58967. æKY AddSearch
  58968. æFc Quickdraw.h
  58969. æT Function
  58970. æTN AA3A
  58971. æD pascal void AddSearch(ColorSearchProcPtr searchProc)
  58972.     = 0xAA3A; 
  58973. æDT AddSearch((ColorSearchProcPtr) searchProc);
  58974. æMM
  58975. æRI V-147
  58976. æC 
  58977. The AddSearch and AddComp routines add a procedure to the head of the current device
  58978. record’s list of search or complement procedures. These routines allocate an SProcRec
  58979. or CProcRec.
  58980.  
  58981. æKY AddComp
  58982. æFc Quickdraw.h
  58983. æT Function
  58984. æTN AA3B
  58985. æD pascal void AddComp(ColorComplementProcPtr compProc)
  58986.     = 0xAA3B; 
  58987. æDT AddComp((ColorComplementProcPtr) compProc);
  58988. æMM
  58989. æRI V-147
  58990. æC  
  58991. The AddSearch and AddComp routines add a procedure to the head of the current device
  58992. record’s list of search or complement procedures. These routines allocate an SProcRec
  58993. or CProcRec.
  58994.  
  58995. æKY DelSearch
  58996. æFc Quickdraw.h
  58997. æT Function
  58998. æTN AA4C
  58999. æD pascal void DelSearch(ColorSearchProcPtr searchProc)
  59000.     = 0xAA4C; 
  59001. æDT DelSearch((ColorSearchProcPtr) searchProc);
  59002. æMM
  59003. æRI V-147
  59004. æC  
  59005. The DelSearch and DelComp procedures remove a custom search or complement procedure
  59006. from the current device record’s list of search or complement procedures. These
  59007. routines dispose of the chain element, but do nothing to the procPtr.
  59008.  
  59009. æKY DelComp
  59010. æFc Quickdraw.h
  59011. æT Function
  59012. æTN AA4D
  59013. æD pascal void DelComp(ColorComplementProcPtr compProc)
  59014.     = 0xAA4D; 
  59015. æDT DelComp((ColorComplementProcPtr) compProc);
  59016. æMM
  59017. æRI V-147
  59018. æC  
  59019. The DelSearch and DelComp procedures remove a custom search or complement procedure
  59020. from the current device record’s list of search or complement procedures. These
  59021. routines dispose of the chain element, but do nothing to the procPtr.
  59022.  
  59023. æKY SubPt
  59024. æFc Quickdraw.h
  59025. æT Function
  59026. æTN A87F
  59027. æD pascal void SubPt(Point src,Point *dst)
  59028.     = 0xA87F; 
  59029. æDT SubPt((Point) src,(Point *) dst);
  59030. æRI I-193
  59031. æC  
  59032. SubPt subtracts the coordinates of srcPt from the coordinates of dstPt, and returns
  59033. the result in dstPt.
  59034.  
  59035. Note:  To get the results of coordinate subtraction returned as a function
  59036.        result, you can use the Toolbox Utility function DeltaPoint.
  59037.  
  59038. æKY SetClientID
  59039. æFc Quickdraw.h
  59040. æT Function
  59041. æTN AA3C
  59042. æD pascal void SetClientID(short id)
  59043.     = 0xAA3C; 
  59044. æDT SetClientID((short) id);
  59045. æRI V-147
  59046. æC  
  59047. The SetClientID procedure sets the gdID field in the current device record to identify
  59048. this client program to its search and complement procedures.
  59049.  
  59050. æKY ProtectEntry
  59051. æFc Quickdraw.h
  59052. æT Function
  59053. æTN AA3D
  59054. æD pascal void ProtectEntry(short index,Boolean protect)
  59055.     = 0xAA3D; 
  59056. æDT ProtectEntry((short) index,(Boolean) protect);
  59057. æRI V-143
  59058. æC  
  59059. The ProtectEntry procedure protects or removes protection from an entry in the current
  59060. device’s color table, depending on the value of the protect parameter.  A protected
  59061. entry can’t be changed by other clients.  It returns a protection error if it attempts
  59062. to protect an already protected entry. However, it can remove protection from any
  59063. entry.
  59064.  
  59065. æKY equalpt
  59066. æFc Quickdraw.h
  59067. æT Function
  59068. æD Boolean equalpt(Point *pt1,Point *pt2); 
  59069. æDT Boolean myVariable = equalpt((Point *) pt1,(Point *) pt2);
  59070. æRI I-193
  59071. æC  
  59072. EqualPt compares the two given points and returns TRUE if they’re equal or FALSE if
  59073. not.
  59074.  
  59075. æKY ReserveEntry
  59076. æFc Quickdraw.h
  59077. æT Function
  59078. æTN AA3E
  59079. æD pascal void ReserveEntry(short index,Boolean reserve)
  59080.     = 0xAA3E; 
  59081. æDT ReserveEntry((short) index,(Boolean) reserve);
  59082. æRI V-143
  59083. æC  
  59084. The ReserveEntry procedure reserves or dereserves an entry in the current color
  59085. table, depending on the value of the reserve parameter.  A reserved entry cannot be
  59086. matched by another client’s search procedure, and will never be returned to another
  59087. client by Color2Index or other routines that depend on it
  59088. (such as RGBForeColor, RGBBackColor, SetCPixel, and so forth).  You could use this
  59089. routine to selectively protect a color for color table animation.
  59090.  
  59091. ReserveEntry copies the low byte of gdID into the low byte of ColorSpec.value when
  59092. reserving an entry, and leaves the high byte alone. It acts like a selective protection,
  59093. and does not allow any changes if the current gdID is different than the one in the
  59094. colorSpec.value field of the reserved entry. If a requested match is already reserved,
  59095. ReserveEntry returns a protection error. Any entry can be dereserved.
  59096.  
  59097. æKY SetEntries
  59098. æFc Quickdraw.h
  59099. æT Function
  59100. æTN AA3F
  59101. æD pascal void SetEntries(short start,short count,CSpecArray aTable)
  59102.     = 0xAA3F; 
  59103. æDT SetEntries((short) start,(short) count,(CSpecArray) aTable);
  59104. æRI V-143
  59105. æC  
  59106. The SetEntries procedure sets a group of color table entries for the current gDevice,
  59107. starting at a given position for the specified number of entries. The pointer aTable
  59108. points into a cSpecArray, not into a color table.  The colorSpec.value field of the
  59109. entries must be in the logical range for the target card’s assigned pixel depth.
  59110. Thus, with a 4-bit pixel size, the colorSpec.value fields should be in the range 1 to
  59111. 15. With an 8-bit pixel size the range is 0 to 255.  Note that all values are zero-based;
  59112. for example, to set three entries, pass two in the count parameter.
  59113.  
  59114. Note:  Palette Manager routines should be used instead of the SetEntries
  59115.        routine for applications that will run in a multiscreen or
  59116.        multitasking environment.
  59117.  
  59118. The SetEntries positional information works in logical space, rather than in the
  59119. actual memory space used by the hardware. Requesting a change at position four in the
  59120. color table may not modify color table entry four in the hardware, but it does correctly
  59121. change the color on the screen for any pixels with a value of four in the video card.
  59122. The SetEntries mode characterized by a start position and a length is called sequence
  59123. mode. In this case, new colors are sequentially loaded into the hardware in the same
  59124. order as the aTable, the clientID fields for changed entries are copied from the
  59125. current device’s gdID field, and the colorSpec.value fields are ignored.
  59126.  
  59127. The other SetEntries mode is called index mode. It allows the cSpecArray to specify
  59128. where the data will be installed on an entry-by-entry basis. To use this mode, pass
  59129. –1 for the start position, with a valid count and a pointer to the cSpecArray. Each
  59130. entry is installed into the color table at the position specified by the colorSpec.value
  59131. field of each entry in the cSpecArray. In the current device’s color table, all
  59132. changed entries’ colorSpec.value fields are assigned the gdID value.
  59133.  
  59134. When color table entries are changed, all cached fonts are invalidated, and the seed
  59135. number is changed so that the next drawing operation will rebuild the inverse table.
  59136. If any of the requested entries are protected or out of range, a protection error is
  59137. returned, and nothing happens. If a requested entry is reserved, it can only be
  59138. changed if the current gdID matches the low byte of the intended ColorSpec.value
  59139. field.
  59140.  
  59141. æKY ptinrect
  59142. æFc Quickdraw.h
  59143. æT Function
  59144. æD Boolean ptinrect(Point *pt,const Rect *r); 
  59145. æDT Boolean myVariable = ptinrect((Point *) pt,(const Rect *) r);
  59146. æRI I-175
  59147. æC  
  59148. PtInRect determines whether the pixel below and to the right of the given coordinate
  59149. point is enclosed in the specified rectangle, and returns TRUE if so or FALSE if
  59150. not.
  59151.  
  59152. æKY SaveEntries
  59153. æFc Quickdraw.h
  59154. æT Function
  59155. æTN AA49
  59156. æD pascal void SaveEntries(CTabHandle srcTable,CTabHandle resultTable,ReqListRec *selection)
  59157.     = 0xAA49; 
  59158. æDT SaveEntries((CTabHandle) srcTable,(CTabHandle) resultTable,(ReqListRec *) selection);
  59159. æRI V-144
  59160. æC  
  59161. SaveEntries saves a selection of entries from srcTable into resultTable. The entries
  59162. to be set are enumerated in the selection parameter, which uses the ReqListRec data
  59163. structure shown below. (These values are offsets into colorTable, not the contents of
  59164. the colorSpec.value field.)
  59165.  
  59166. TYPE
  59167.   ReqListRec = RECORD
  59168.                  reqLSize:  INTEGER;                 {request list size –1}
  59169.                  reqLData:  ARRAY [0..0] of INTEGER  {request list data}
  59170.                END;
  59171.  
  59172. If an entry is not present in srcTable, then that position of the requestList is set
  59173. to colReqErr, and that position of resultTable has random values returned. If one or
  59174. more entries are not found, then an error code is posted to QDError; however, for
  59175. every entry in selection which is not colReqErr, the values in resultTable are valid.
  59176. Note that srcTable and selection are assumed to have the same number of entries.
  59177.  
  59178. SaveEntries optionally allows NIL as its source color table parameter. If NIL is
  59179. used, the current device’s color table is used as the source. The output of SaveEntries
  59180. is the same as the input for RestoreEntries, except for the order.
  59181.  
  59182. æKY RestoreEntries
  59183. æFc Quickdraw.h
  59184. æT Function
  59185. æTN AA4A
  59186. æD pascal void RestoreEntries(CTabHandle srcTable,CTabHandle dstTable,ReqListRec *selection)
  59187.     = 0xAA4A; 
  59188. æDT RestoreEntries((CTabHandle) srcTable,(CTabHandle) dstTable,(ReqListRec *) selection);
  59189. æRI V-144
  59190. æC 
  59191. RestoreEntries sets a selection of entries from srcTable into dstTable, but doesn’t
  59192. rebuild the inverse table. The dstTable entries to be set are enumerated in the
  59193. selection parameter, which uses the ReqListRec data structure shown in the SetEntries
  59194. routine description. (These values are offsets into the srcTable, not the contents of
  59195. the colorSpec.value field.)
  59196.  
  59197. If a request is beyond the end of the dstTable, that position of the requestList is
  59198. set to colReqErr, and an error is returned. Note that srcTable and selection are
  59199. assumed to have the same number of entries.
  59200.  
  59201. If dstTbl is NIL, or points to the device color table, the current device’s color
  59202. table is updated, and the hardware is updated to these new colors. The seed is not
  59203. changed, so no invalidation occurs (this may cause RGBForeColor to act strangely).
  59204. This routine ignores protection and reservation of color table entries.
  59205.  
  59206. Generally, the Palette Manager is used to give an application its own set of colors;
  59207. use of RestoreEntries should be limited to special-purpose applications. RestoreEntries
  59208. allows you to change the colorTable without changing the ctSeed for the affected
  59209. colorTable. You can execute the application code and then use RestoreEntries to put
  59210. the original colors back in. However, in some cases things in the background may
  59211. appear in the wrong colors, since they were never redrawn. To avoid this, the application
  59212. must build its own new inverse table and redraw the background. If RestoreEntries
  59213. were then used, the ctSeed would have to be explicitly changed to clean up correctly.
  59214.  
  59215. æKY pt2rect
  59216. æFc Quickdraw.h
  59217. æT Function
  59218. æD void pt2rect(Point *pt1,Point *pt2,const Rect *destRect); 
  59219. æDT pt2rect((Point *) pt1,(Point *) pt2,(const Rect *) destRect);
  59220. æRI I-175
  59221. æC  
  59222. Pt2Rect returns the smallest rectangle that encloses the two given points.
  59223.  
  59224. æKY QDError
  59225. æFc Quickdraw.h
  59226. æT Function
  59227. æTN AA40
  59228. æD pascal short QDError(void)
  59229.     = 0xAA40; 
  59230. æDT short myVariable = QDError()(void);
  59231. æRI V-145
  59232. æC  
  59233. The QDError routine returns the error result from the last QuickDraw or Color Manager
  59234. call.  This routine is even more useful with 32-Bit QuickDraw.  It is important that
  59235. you check for errors after every QuickDraw call.  For more information, see the
  59236. 32-Bit QuickDraw documentation.
  59237.  
  59238. æKY GetMaskTable
  59239. æFc Quickdraw.h
  59240. æT Function
  59241. æD pascal Ptr GetMaskTable(void); 
  59242. æDT Ptr myVariable = GetMaskTable()(void);
  59243. æRI IV-25 
  59244. æC  
  59245. The function GetMaskTable, accessible only from assembly language, returns in register
  59246. A0 a pointer to a ROM table containing the following useful masks:
  59247.  
  59248.   .WORD $0000,$8000,$C000,$E000    ;Table of 16 right masks
  59249.   .WORD $F000,$F800,$FC00,$FE00
  59250.   .WORD $FF00,$FF80,$FFC0,$FFE0
  59251.   .WORD $FFF0,$FFF8,$FFFC,$FFFE
  59252.  
  59253.   .WORD $FFFF,$7FFF,$3FFF,$1FFF    ;Table of 16 left masks
  59254.   .WORD $0FFF,$07FF,$03FF,$01FF
  59255.   .WORD $00FF,$007F,$003F,$001F
  59256.   .WORD $000F,$0007,$0003,$0001
  59257.  
  59258.   .WORD $8000,$4000,$2000,$1000    ;Table of 16 bit masks
  59259.   .WORD $0800,$0400,$0200,$0100
  59260.   .WORD $0080,$0040,$0020,$0010
  59261.   .WORD $0008,$0004,$0002,$0001
  59262.  
  59263. æKY pttoangle
  59264. æFc Quickdraw.h
  59265. æT Function
  59266. æD void pttoangle(const Rect *r,Point *pt,short *angle); 
  59267. æDT pttoangle((const Rect *) r,(Point *) pt,(short *) angle);
  59268. æRI I-175
  59269. æC  
  59270. PtToAngle calculates an integer angle between a line from the center of the rectangle
  59271. to the given point and a line from the center of the rectangle pointing straight up
  59272. (12 o’clock high). The angle is in degrees from 0 to 359, measured clockwise from 12
  59273. o’clock, with 90 degrees at 3 o’clock, 180 at
  59274. 6 o’clock, and 270 at 9 o’clock. Other angles are measured relative to the rectangle:
  59275.  If the line to the given point goes through the top right corner of the rectangle,
  59276. the angle returned is 45 degrees, even if the rectangle isn’t square; if it goes
  59277. through the bottom right corner, the angle is 135 degrees, and so on (see Figure
  59278. 20).
  59279.  
  59280. •••Refer to Figure 20.•••
  59281.  
  59282. Figure 20–PtToAngle
  59283.  
  59284. The angle returned might be used as input to one of the procedures that manipulate
  59285. arcs and wedges, as described below under “Graphic Operations on Arcs and Wedges”.
  59286.  
  59287. æKY ptinrgn
  59288. æFc Quickdraw.h
  59289. æT Function
  59290. æD Boolean ptinrgn(Point *pt,RgnHandle rgn); 
  59291. æDT Boolean myVariable = ptinrgn((Point *) pt,(RgnHandle) rgn);
  59292. æRI I-185
  59293. æC  
  59294. PtInRgn checks whether the pixel below and to the right of the given coordinate point
  59295. is within the specified region, and returns TRUE if so or FALSE if not.
  59296.  
  59297. æKY stdtext
  59298. æFc Quickdraw.h
  59299. æT Function
  59300. æD void stdtext(short count,Ptr textAddr,Point *numer,Point *denom); 
  59301. æDT stdtext((short) count,(Ptr) textAddr,(Point *) numer,(Point *) denom);
  59302. æMM
  59303. æRI I-198, N27-5
  59304. æC  
  59305. StdText is the standard low-level routine for drawing text. It draws text from the
  59306. arbitrary structure in memory specified by textBuf, starting from the first byte and
  59307. continuing for byteCount bytes. Numer and denom specify the scaling factor:  numer.v
  59308. over denom.v gives the vertical scaling, and numer.h over denom.h gives the horizontal
  59309. scaling.
  59310.  
  59311. æKY stdline
  59312. æFc Quickdraw.h
  59313. æT Function
  59314. æD void stdline(Point *newPt); 
  59315. æDT stdline((Point *) newPt);
  59316. æMM
  59317. æRI I-198, N27-5, 6
  59318. æC  
  59319. StdLine is the standard low-level routine for drawing a line. It draws a line from
  59320. the current pen location to the location specified (in local coordinates) by newPt.
  59321.  
  59322. æKY drawstring
  59323. æFc Quickdraw.h
  59324. æT Function
  59325. æD void drawstring(char *s); 
  59326. æDT drawstring((char *) s);
  59327. æRT 26
  59328. æRI I-172, N26, P-83, 170
  59329. æC  
  59330. DrawString calls DrawChar for each character in the given string. The string is
  59331. placed beginning at the current pen location and extending right. No formatting (such
  59332. as carriage returns and line feeds) is performed by QuickDraw. The pen location ends
  59333. up to the right of the last character in the string.
  59334.  
  59335. Warning:  QuickDraw temporarily stores on the stack all of the text you
  59336.           ask it to draw, even if the text will be clipped. When drawing
  59337.           large font sizes or complex style variations, it’s best to draw
  59338.           only what will be visible on the screen. You can determine how
  59339.           many characters will actually fit on the screen by calling the
  59340.           StringWidth function before calling DrawString.
  59341.  
  59342. æKY addpt
  59343. æFc Quickdraw.h
  59344. æT Function
  59345. æD void addpt(Point *src,Point *dst); 
  59346. æDT addpt((Point *) src,(Point *) dst);
  59347. æRI I-193
  59348. æC  
  59349. AddPt adds the coordinates of srcPt to the coordinates of dstPt, and returns the
  59350. result in dstPt.
  59351.  
  59352. æKY stuffhex
  59353. æFc Quickdraw.h
  59354. æT Function
  59355. æD void stuffhex(Ptr thingPtr,char *s); 
  59356. æDT stuffhex((Ptr) thingPtr,(char *) s);
  59357. æRI I-195, P-81
  59358. æC  
  59359. StuffHex stores bits (expressed as a string of hexadecimal digits) into any data
  59360. structure. You can easily create a pattern in your program with StuffHex
  59361. (though more likely, you’ll store patterns in a resource file). For example,
  59362.  
  59363.   StuffHex(@stripes,'0102040810204080')
  59364.  
  59365. places a striped pattern into the pattern variable named stripes.
  59366.  
  59367. Warning:  There’s no range checking on the size of the destination variable.
  59368.           It’s easy to overrun the variable and destroy something if you
  59369.           don’t know what you’re doing.
  59370.  
  59371. æKY stringwidth
  59372. æFc Quickdraw.h
  59373. æT Function
  59374. æD short stringwidth(char *s); 
  59375. æDT short myVariable = stringwidth((char *) s);
  59376. æMM
  59377. æRT 26
  59378. æRI I-173, N26
  59379. æC  
  59380. StringWidth returns the width of the given text string, which it calculates by adding
  59381. the CharWidths of all the characters in the string (see above).
  59382.  
  59383.  
  59384. æKY Resources.h
  59385. æKL addresource
  59386. AddResource
  59387. ChangedResource
  59388. CloseResFile
  59389. Count1Resources
  59390. Count1Types
  59391. CountResources
  59392. CountTypes
  59393. createresfile
  59394. CreateResFile
  59395. CurResFile
  59396. DetachResource
  59397. Get1IndResource
  59398. Get1IndType
  59399. get1namedresource
  59400. Get1NamedResource
  59401. Get1Resource
  59402. GetIndResource
  59403. GetIndType
  59404. GetNamedResource
  59405. getnamedresource
  59406. GetResAttrs
  59407. GetResFileAttrs
  59408. getresinfo
  59409. GetResInfo
  59410. GetResource
  59411. HCreateResFile
  59412. HomeResFile
  59413. HOpenResFile
  59414. InitResources
  59415. LoadResource
  59416. MaxSizeRsrc
  59417. openresfile
  59418. OpenResFile
  59419. openrfperm
  59420. OpenRFPerm
  59421. ReleaseResource
  59422. ResError
  59423. RGetResource
  59424. RmveResource
  59425. RsrcMapEntry
  59426. RsrcZoneInit
  59427. SetResAttrs
  59428. SetResFileAttrs
  59429. setresinfo
  59430. SetResInfo
  59431. SetResLoad
  59432. SetResPurge
  59433. SizeResource
  59434. Unique1ID
  59435. UniqueID
  59436. UpdateResFile
  59437. UseResFile
  59438. WriteResource
  59439.  
  59440. mapChanged
  59441. mapCompact
  59442. mapFalse
  59443. mapReadOnly
  59444. mapTrue
  59445. resChanged
  59446. resLocked
  59447. resPreload
  59448. resProtected
  59449. resPurgeable
  59450. resSysHeap
  59451.  
  59452. æKY resSysHeap
  59453. æFc Resources.h
  59454. æT #define
  59455. æD #define resSysHeap 64 /*System or application heap?*/
  59456. æC 
  59457. The Resource Manager provides a predefined constant for each attribute, in which the
  59458. bit corresponding to that attribute is set.
  59459.  
  59460. #define  resSysHeap     64   /*set if read into system heap*/
  59461. #define  resPurgeable   32   /*set if purgeable*/
  59462. #define  resLocked      16   /*set if locked*/
  59463. #define  resProtected   8    /*set if protected*/
  59464. #define  resPreload     4    /*set if to be preloaded*/
  59465. #define  resChanged     2    /*set if to be written to resource file*/
  59466.  
  59467. Warning:  Your application should not change the setting of bit 0 or 7, nor
  59468.           should it set the resChanged attribute directly. (ResChanged is set
  59469.           as a side effect of the procedure you call to tell the Resource
  59470.           Manager that you’ve changed a resource.)
  59471.  
  59472. The resSysHeap attribute should not be set for your application’s resources. If a
  59473. resource with this attribute set is too large for the system heap, the bit will be
  59474. cleared, and the resource will be read into the application heap.
  59475.  
  59476. Since a locked resource is neither relocatable nor purgeable, the resLocked attribute
  59477. overrides the resPurgeable attribute; when resLocked is set, the resource will not be
  59478. purgeable regardless of whether resPurgeable is set.
  59479.  
  59480. If the resProtected attribute is set, the application can’t use Resource Manager
  59481. routines to change the ID number or name of the resource, modify its contents, or
  59482. remove the resource from the resource file. The routine that sets the resource attributes
  59483. may be called, however, to remove the protection or just change some of the other
  59484. attributes.
  59485.  
  59486. The resPreload attribute tells the Resource Manager to read this resource into memory
  59487. immediately after opening the resource file. This is useful, for example, if you
  59488. immediately want to draw ten icons stored in the file; rather than read and draw each
  59489. one individually in turn, you can have all of them read in when the file is opened
  59490. and just draw all ten.
  59491.  
  59492. The resChanged attribute is used only while the resource map is in memory; it must be
  59493. 0 in the resource file. It tells the Resource Manager whether this resource has been
  59494. changed.
  59495.  
  59496. æKY resPurgeable
  59497. æFc Resources.h
  59498. æT #define
  59499. æD #define resPurgeable 32 /*Purgeable resource?*/
  59500. æC 
  59501.  
  59502. æKY resLocked
  59503. æFc Resources.h
  59504. æT #define
  59505. æD #define resLocked 16 /*Load it in locked?*/
  59506. æC 
  59507.  
  59508. æKY resProtected
  59509. æFc Resources.h
  59510. æT #define
  59511. æD #define resProtected 8 /*Protected?*/
  59512. æC 
  59513.  
  59514. æKY resPreload
  59515. æFc Resources.h
  59516. æT #define
  59517. æD #define resPreload 4 /*Load in on OpenResFile?*/
  59518. æC 
  59519.  
  59520. æKY resChanged
  59521. æFc Resources.h
  59522. æT #define
  59523. æD #define resChanged 2 /*Resource changed?*/
  59524. æC 
  59525.  
  59526. æKY mapReadOnly
  59527. æFc Resources.h
  59528. æT #define
  59529. æD #define mapReadOnly 128 /*Resource file read-only*/
  59530. æC 
  59531. The routines described in this section allow advanced programmers to have even greater
  59532. control over resource file operations. Just as individual resources have attributes,
  59533. an entire resource file also has attributes, which these routines manipulate. Like
  59534. the attributes of individual resources, resource file attributes are specified by
  59535. bits in the low-order byte of a word. The Resource Manager provides the following
  59536. masks for setting or testing these bits:
  59537.  
  59538. #define mapReadOnly    128   /*set if file is read-only*/
  59539. #define mapCompact     64    /*set to compact file on update*/
  59540. #define mapChanged     32    /*set to write map on update*/
  59541.  
  59542. When the mapReadOnly attribute is set, the Resource Manager will neither write anything
  59543. to the resource file nor check whether the file can be written out to the disk when
  59544. the resource map is modified. When this attribute is set, UpdateResFile and WriteResource
  59545. will do nothing, but the ResError function will return the result code noErr.
  59546.  
  59547. Warning:  If you set mapReadOnly but then later clear it, the resource file
  59548.           will be written even if there’s no room for it on the disk. This
  59549.           would destroy the file.
  59550.  
  59551. The mapCompact attribute causes the resource file to be compacted when the file is
  59552. updated. It’s set by the Resource Manager when a resource is removed, or when a
  59553. resource is made larger and thus has to be written at the end of the resource file.
  59554. You may want to set mapCompact to force compaction when you’ve only made resources
  59555. smaller.
  59556.  
  59557. The mapChanged attribute causes the resource map to be written to the resource file
  59558. when the file is updated. It’s set by the Resource Manager when you call ChangedResource
  59559. or when you add or remove a resource. You can set mapChanged if, for example, you’ve
  59560. changed resource attributes only and don’t want to call ChangedResource because you
  59561. don’t want the resource data to be written out.
  59562.  
  59563. æKY mapCompact
  59564. æFc Resources.h
  59565. æT #define
  59566. æD #define mapCompact 64 /*Compact resource file*/
  59567. æC 
  59568.  
  59569. æKY mapChanged
  59570. æFc Resources.h
  59571. æT #define
  59572. æD #define mapChanged 32 /*Write map out at updat*/
  59573. æC 
  59574.  
  59575. æKY mapTrue
  59576. æFc Resources.h
  59577. æT #define
  59578. æD 
  59579. /* Values for setting RomMapInsert and TmpResLoad */
  59580.  
  59581. #define mapTrue 0xFFFF /*insert ROM map w/ TmpResLoad = TRUE.*/
  59582. æC 
  59583.  
  59584. æKY mapFalse
  59585. æFc Resources.h
  59586. æT #define
  59587. æD #define mapFalse 0xFF00 /*insert ROM map w/ TmpResLoad = FALSE.*/
  59588. æC 
  59589.  
  59590. æKY InitResources
  59591. æFc Resources.h
  59592. æT Function
  59593. æTN A995
  59594. æD pascal short InitResources(void)
  59595.     = 0xA995; 
  59596. æDT short myVariable = InitResources()(void);
  59597. æMM
  59598. æRI I-114
  59599. æC  
  59600. InitResources is called by the system when it starts up, and should not be called by
  59601. the application. It initializes the Resource Manager, opens the system resource file,
  59602. reads the resource map from the file into memory, and returns a reference number for
  59603. the file.
  59604.  
  59605. Assembly-language note:  The name of the system resource file is stored in
  59606.                          the global variable SysResName; the reference number
  59607.                          for the file is stored in the global variable SysMap.
  59608.                          A handle to the resource map of the system resource
  59609.                          file is stored in the variable SysMapHndl.
  59610.  
  59611. Note:  The application doesn’t need the reference number for the system
  59612.        resource file, because every Resource Manager routine that has a
  59613.        reference number as a parameter interprets 0 to mean the system
  59614.        resource file.
  59615.  
  59616. æKY RsrcZoneInit
  59617. æFc Resources.h
  59618. æT Function
  59619. æTN A996
  59620. æD pascal void RsrcZoneInit(void)
  59621.     = 0xA996; 
  59622. æDT RsrcZoneInit()(void);
  59623. æMM
  59624. æRI I-114
  59625. æC  
  59626. RsrcZoneInit is called automatically when your application starts up, to initialize
  59627. the resource map read from the system resource file; normally you’ll have no need to
  59628. call it directly. It “cleans up” after any resource access that may have been done by
  59629. a previous application. First it closes all open resource files except the system
  59630. resource file. Then, for every system resource that was read into the application
  59631. heap (that is, whose resSysHeap attribute is 0), it replaces the handle to that
  59632. resource in the resource map with NIL. This lets the Resource Manager know that the
  59633. resource will have to be read in again (since the previous application heap is no 
  59634. longer around).
  59635.  
  59636. æKY CloseResFile
  59637. æFc Resources.h
  59638. æT Function
  59639. æTN A99A
  59640. æD pascal void CloseResFile(short refNum)
  59641.     = 0xA99A; 
  59642. æDT CloseResFile((short) refNum);
  59643. æMM
  59644. æRT 116
  59645. æRI I-115, N116-1
  59646. æC  
  59647. Given the reference number of a resource file, CloseResFile does the following:
  59648.  
  59649.   •  updates the resource file by calling the UpdateResFile procedure
  59650.   •  for each resource in the resource file, releases the memory it occupies
  59651.      by calling the ReleaseResource procedure
  59652.   •  releases the memory occupied by the resource map
  59653.   •  closes the resource file
  59654.  
  59655. If there’s no resource file open with the given reference number, CloseResFile will
  59656. do nothing and the ResError function will return the result code resFNotFound. A
  59657. refNum of 0 represents the system resource file, but if you ask to close this file,
  59658. CloseResFile first closes all other open resource files.
  59659.  
  59660. A CloseResFile of every open resource file (except the system resource file) is done
  59661. automatically when the application terminates. So you only need to call CloseResFile
  59662. if you want to close a resource file before the application terminates.
  59663.  
  59664. æKY ResError
  59665. æFc Resources.h
  59666. æT Function
  59667. æTN A9AF
  59668. æD pascal short ResError(void)
  59669.     = 0xA9AF; 
  59670. æDT short myVariable = ResError()(void);
  59671. æRT 78,116, 185, 214
  59672. æRI I-116
  59673. æC 
  59674. Called after one of the various Resource Manager routines that may result in an error
  59675. condition, ResError returns a result code identifying the error, if any. If no error
  59676. occurred, it returns the result code
  59677.  
  59678. CONST  noErr    = 0;    {no error}
  59679.  
  59680. If an error occurred at the Operating System level, it returns an Operating System
  59681. result code, such as the File Manager “disk I/O” error or the Memory Manager “out of
  59682. memory” error. (See Appendix A for a list of all result codes.) If an error happened
  59683. at the Resource Manager level, ResError returns one of the following result codes:
  59684.  
  59685. CONST  resNotFound     = -192;    {resource not found}
  59686.        resFNotFound    = -193;    {resource file not found}
  59687.        addResFailed    = -194;    {AddResource failed}
  59688.        rmvResFailed    = -196;    {RmveResource failed}
  59689.  
  59690. Each routine description tells which errors may occur for that routine. You can also
  59691. check for an error after system startup, which calls InitResources, and application
  59692. startup, which opens the application’s resource file.
  59693.  
  59694. Warning:  In certain cases, the ResError function will return noError even
  59695.           though a Resource Manager routine was unable to perform the requested
  59696.           operation; the routine descriptions give details about the
  59697.           circumstances under which this will happen.
  59698.  
  59699. Assembly-language note:  The current value of ResError is stored in the global
  59700.                          variable ResErr. In addition, you can specify a
  59701.                          procedure to be called whenever there’s an error by
  59702.                          storing the address of the procedure in the global
  59703.                          variable ResErrProc (which is normally 0). Before
  59704.                          returning a result code other than noErr, the ResError
  59705.                          function places that result code in register D0 and
  59706.                          calls your procedure.
  59707.  
  59708. •••Refer to Technical Note #78:•••
  59709.  
  59710. In the 64K ROM, some error conditions resulting from certain Resource Manager routines
  59711. are not reported by the ResError function. Two additional result codes are defined in
  59712. the 128K ROM version of the Resource Manager:
  59713.  
  59714. CONST  resAttrErr = 198; {attribute does not permit operation}
  59715.        mapReadErr = 199; {map does not permit operation}
  59716.  
  59717. In the 128K ROM, the following error conditions are reported by ResError:
  59718.  
  59719.   •  The OpenResFile function checks to see that the information in the
  59720.      resource map is internally consistent; if it isn’t, ResError returns
  59721.      mapReadError.
  59722.   •  The CloseResFile procedure calls UpdateResFile. If UpdateResFile returns
  59723.      a nonzero result code, that result code will be returned by CloseResFile.
  59724.   •  If you provide an index to GetIndResource (or Get1IndResource) that’s
  59725.      either 0 or negative, the ResError function will return the result code
  59726.      resNotFound.
  59727.   •  If you call DetachResource to detach a resource whose resChanged attribute
  59728.      has been set, ResError will return the result code resAttrErr.
  59729.   •  If you call SetResInfo but the resProtected attribute is set, ResError
  59730.      will return the result code resAttrErr.
  59731.   •  If you call ChangedResource but the resProtected attribute for the
  59732.      modified resource is set, the ResError function will return the result
  59733.      code resAttrErr.
  59734.   •  If you call UpdateResFile but the mapReadOnly attribute for the resource
  59735.      file is set (described in the “Advanced Routines” section of the Resource
  59736.      Manager chapter), ResError will return the result code mapReadErr.
  59737.  
  59738. Warning:  If you call the GetResource and Get1Resource functions with a
  59739.           resource type that isn’t in any open resource file, they return NIL
  59740.           but the ResError function will return the result code noErr. With
  59741.           these calls, you must check that the handle returned is nonzero.
  59742.  
  59743. æKY CurResFile
  59744. æFc Resources.h
  59745. æT Function
  59746. æTN A994
  59747. æD pascal short CurResFile(void)
  59748.     = 0xA994; 
  59749. æDT short myVariable = CurResFile()(void);
  59750. æRI I-116
  59751. æC     CurResFile returns the reference number of the current resource file
  59752.  
  59753. When calling the CurResFile and HomeResFile routines, described below, be aware that
  59754. for the system resource file the actual reference number is returned. You needn’t
  59755. worry about this number being used (instead of 0) in the routines that require a
  59756. reference number; those routines recognize both 0 and the actual reference number as
  59757. referring to the system resource file.
  59758.  
  59759. CurResFile returns the reference number of the current resource file. You can call it
  59760. when the application starts up to get the reference number of its resource file.
  59761.  
  59762. Assembly-language note:  The reference number of the current resource file is
  59763.                          stored in the global variable CurMap.
  59764.  
  59765. æKY HomeResFile
  59766. æFc Resources.h
  59767. æT Function
  59768. æTN A9A4
  59769. æD pascal short HomeResFile(Handle theResource)
  59770.     = 0xA9A4; 
  59771. æDT short myVariable = HomeResFile((Handle) theResource);
  59772. æRI I-117
  59773. æC 
  59774. When calling the CurResFile and HomeResFile routines, described below, be aware that
  59775. for the system resource file the actual reference number is returned. You needn’t
  59776. worry about this number being used (instead of 0) in the routines that require a
  59777. reference number; those routines recognize both 0 and the actual reference number as
  59778. referring to the system resource file.
  59779.  
  59780. Given a handle to a resource, HomeResFile returns the reference number of the resource
  59781. file containing that resource. If the given handle isn’t a handle to a resource,
  59782. HomeResFile will return –1 and the ResError function will return the result code
  59783. resNotFound.
  59784.  
  59785. æKY CreateResFile
  59786. æFc Resources.h
  59787. æT Function
  59788. æTN A9B1
  59789. æD pascal void CreateResFile(const Str255 fileName)
  59790.     = 0xA9B1; 
  59791. æDT CreateResFile((const Str255) fileName);
  59792. æMM
  59793. æRT 101, 214
  59794. æRI I-114, N101
  59795. æC  
  59796. When calling the CreateResFile or OpenResFile routine, described below, you specify a
  59797. resource file by its file name; the routine assumes that the file has a version
  59798. number of 0 and is on the default volume. (Version numbers and volumes are described
  59799. in the File Manager chapter.) If you want the routine to apply to a file on another
  59800. volume, just set the default volume to that volume.
  59801.  
  59802. •••Refer to Technical Notes #101 & #214:•••
  59803.  
  59804. CreateResFile creates a resource file containing no resource data. If there’s no file
  59805. at all with the given name, it also creates an empty data fork for the file. If
  59806. there’s already a resource file with the given name (that is, a resource fork that
  59807. isn’t empty), CreateResFile will do nothing and the ResError function will return an
  59808. appropriate Operating System result code.
  59809.  
  59810. Note:  Before you can work with the resource file, you need to open it with
  59811.        OpenResFile.
  59812.  
  59813. æKY OpenResFile
  59814. æFc Resources.h
  59815. æT Function
  59816. æTN A997
  59817. æD pascal short OpenResFile(const Str255 fileName)
  59818.     = 0xA997; 
  59819. æDT short myVariable = OpenResFile((const Str255) fileName);
  59820. æMM
  59821. æRT 46, 46,74, 78, 101, 185, 214,232 
  59822. æRI I-115, N46-1, N78-1, 2, N101-2
  59823. æC 
  59824. When calling the CreateResFile or OpenResFile routine, described below, you specify a
  59825. resource file by its file name; the routine assumes that the file has a version
  59826. number of 0 and is on the default volume. (Version numbers and volumes are described
  59827. in the File Manager chapter.) If you want the routine to apply to a file on another
  59828. volume, just set the default volume to that volume.
  59829.  
  59830. •••Refer to Technical Notes #101 & #214:•••
  59831.  
  59832. OpenResFile opens the resource file having the given name and makes it the current
  59833. resource file. It reads the resource map from the file into memory and returns a
  59834. reference number for the file. It also reads in every resource whose resPreload
  59835. attribute is set. If the resource file is already open, it doesn’t make it the current
  59836. resource file; it simply returns the reference number.
  59837.  
  59838. Note:  You don’t have to call OpenResFile to open the system resource file
  59839.        or the application’s resource file, because they’re opened when the
  59840.        system and the application start up, respectively. To get the reference
  59841.        number of the application’s resource file, you can call CurResFile after
  59842.        the application starts up (before you open any other resource file).
  59843.  
  59844. If the file can’t be opened, OpenResFile will return –1 and the ResError function
  59845. will return an appropriate Operating System result code. For example, an error occurs
  59846. if there’s no resource file with the given name.
  59847.  
  59848. •••Refer to Technical Notes #74 & #232:•••
  59849.  
  59850. Note:  To open a resource file simply for block-level operations such as
  59851.        copying files (without reading the resource map into memory), you
  59852.        can call the File Manager function OpenRF.
  59853.  
  59854. Assembly-language note:  A handle to the resource map of the most recently
  59855.                          opened resource file is stored in the global variable
  59856.                          TopMapHndl.
  59857.  
  59858. æKY UseResFile
  59859. æFc Resources.h
  59860. æT Function
  59861. æTN A998
  59862. æD pascal void UseResFile(short refNum)
  59863.     = 0xA998; 
  59864. æDT UseResFile((short) refNum);
  59865. æRI I-117
  59866. æC 
  59867. Given the reference number of a resource file, UseResFile sets the current resource
  59868. file to that file. If there’s no resource file open with the given reference number,
  59869. UseResFile will do nothing and the ResError function will return the result code
  59870. resFNotFound. A refNum of 0 represents the system resource file.
  59871.  
  59872. Open resource files are arranged as a linked list; the most recently opened file is
  59873. at the end of the list and is the first one the Resource Manager searches when looking
  59874. for a resource. UseResFile lets you start the search with a file opened earlier; the
  59875. file(s) following it in the list are then left out of the search process. Whenever a
  59876. new resource file is opened, it’s added to the end of the list; this overrides any
  59877. previous calls to UseResFile, causing the entire list of open resource files to be
  59878. searched. For example, assume there are four open resource files (R0 through R3); the
  59879. search order is R3, R2, R1, R0. If you call UseResFile(R2), the search order becomes
  59880. R2, R1, R0; R3 is no longer searched. If you then open a fifth resource file (R4),
  59881. it’s added to the end of the list and the search order becomes R4, R3, R2, R1, R0.
  59882.  
  59883. This procedure is useful if you no longer want to override a system resource with one
  59884. by the same name in your application’s resource file. You can call UseResFile(0) to
  59885. leave the application resource file out of the search, causing only the system resource
  59886. file to be searched.
  59887.  
  59888. Warning:  Early versions of some desk accessories may, upon closing, always
  59889.           set the current resource file to the one opened just before the
  59890.           accessory, ignoring any additional resource files that may have
  59891.           been opened while the accessory was open. To be safe, whenever a
  59892.           desk accessory may have been in use, call UseResFile to ensure
  59893.           access to resource files opened while the accessory was open.
  59894.  
  59895. æKY CountTypes
  59896. æFc Resources.h
  59897. æT Function
  59898. æTN A99E
  59899. æD pascal short CountTypes(void)
  59900.     = 0xA99E; 
  59901. æDT short myVariable = CountTypes()(void);
  59902. æRI I-117
  59903. æC 
  59904. CountTypes returns the number of resource types in all open resource files.
  59905.  
  59906. æKY Count1Types
  59907. æFc Resources.h
  59908. æT Function
  59909. æTN A81C
  59910. æD pascal short Count1Types(void)
  59911.     = 0xA81C; 
  59912. æDT short myVariable = Count1Types()(void);
  59913. æRI IV-15
  59914. æC  
  59915. Count1Types is the same as CountTypes except that it returns the number of resource
  59916. types in the current resource file only.
  59917.  
  59918. æKY GetIndType
  59919. æFc Resources.h
  59920. æT Function
  59921. æTN A99F
  59922. æD pascal void GetIndType(ResType *theType,short index)
  59923.     = 0xA99F; 
  59924. æDT GetIndType((ResType *) theType,(short) index);
  59925. æRI I-117
  59926. æC  
  59927. Given an index ranging from 1 to CountTypes (above), GetIndType returns a resource
  59928. type in theType. Called repeatedly over the entire range for the index, it returns
  59929. all the resource types in all open resource files. If the given index isn’t in the
  59930. range from 1 to CountTypes, GetIndType returns four NULL characters (ASCII code 0).
  59931.  
  59932. æKY Get1IndType
  59933. æFc Resources.h
  59934. æT Function
  59935. æTN A80F
  59936. æD pascal void Get1IndType(ResType *theType,short index)
  59937.     = 0xA80F; 
  59938. æDT Get1IndType((ResType *) theType,(short) index);
  59939. æMM
  59940. æRI IV-15
  59941. æC 
  59942. Assembly-language note:  The macro you invoke to call Get1IndType from assembly
  59943.                          language is named _Get1IxType.
  59944.  
  59945. Get1IndType is the same as GetIndType except that it searches the current resource
  59946. file only. Given an index ranging from 1 to Count1Types (above), Get1IndType returns
  59947. a resource type in theType. Called repeatedly over the entire range for the index, it
  59948. returns all the resource types in the current resource file. If the given index isn’t
  59949. in the range from 1 to Count1Types, Get1IndType returns four NULL characters (ASCII
  59950. code 0).
  59951.  
  59952. æKY SetResLoad
  59953. æFc Resources.h
  59954. æT Function
  59955. æTN A99B
  59956. æD pascal void SetResLoad(Boolean load)
  59957.     = 0xA99B; 
  59958. æDT SetResLoad((Boolean) load);
  59959. æRT 50
  59960. æRI I-118, N50-1
  59961. æC 
  59962. Normally, the routines that return handles to resources read the resource data into
  59963. memory if it’s not already in memory. SetResLoad(FALSE) affects all those routines so
  59964. that they will not read the resource data into memory and will return an empty handle.
  59965. Furthermore, resources whose resPreload attribute is set will not be read into memory
  59966. when a resource file is opened.
  59967.  
  59968. Warning:  If you call SetResLoad(FALSE), be sure to restore the normal state
  59969.           as soon as possible, because other parts of the Toolbox that call
  59970.           the Resource Manager rely on it.
  59971.  
  59972. Assembly-language note:  The current SetResLoad state is stored in the global
  59973.                          variable ResLoad.
  59974.  
  59975. æKY CountResources
  59976. æFc Resources.h
  59977. æT Function
  59978. æTN A99C
  59979. æD pascal short CountResources(ResType theType)
  59980.     = 0xA99C; 
  59981. æDT short myVariable = CountResources((ResType) theType);
  59982. æRI I-118
  59983. æC 
  59984. CountResources returns the total number of resources of the given type in all open
  59985. resource files.
  59986.  
  59987. æKY Count1Resources
  59988. æFc Resources.h
  59989. æT Function
  59990. æTN A80D
  59991. æD pascal short Count1Resources(ResType theType)
  59992.     = 0xA80D; 
  59993. æDT short myVariable = Count1Resources((ResType) theType);
  59994. æRI IV-15 
  59995. æC 
  59996. Count1Resources is the same as CountResources except that it returns the total number
  59997. of resources of the given type in the current resource file only.
  59998.  
  59999. æKY GetIndResource
  60000. æFc Resources.h
  60001. æT Function
  60002. æTN A99D
  60003. æD pascal Handle GetIndResource(ResType theType,short index)
  60004.     = 0xA99D; 
  60005. æDT Handle myVariable = GetIndResource((ResType) theType,(short) index);
  60006. æMM
  60007. æRI I-118
  60008. æC 
  60009. Given an index ranging from 1 to CountResources(theType), GetIndResource returns a
  60010. handle to a resource of the given type (see CountResources, above). Called repeatedly
  60011. over the entire range for the index, it returns handles to all resources of the given
  60012. type in all open resource files. GetIndResource reads the resource data into memory
  60013. if it’s not already in memory, unless
  60014. you’ve called SetResLoad(FALSE).
  60015.  
  60016. Warning:  The handle returned will be an empty handle if you’ve called
  60017.           SetResLoad(FALSE) (and the data isn’t already in memory). The handle
  60018.           will become empty if the resource data for a purgeable resource is
  60019.           read in but later purged. (You can test for an empty handle with,
  60020.           for example, myHndl^ = NIL.) To read in the data and make the handle
  60021.           no longer be empty, you can call LoadResource.
  60022.  
  60023. GetIndResource returns handles for all resources in the most recently opened resource
  60024. file first, and then for those in the resource files opened before it, in the reverse
  60025. of the order that they were opened.
  60026.  
  60027. Note:  The UseResFile procedure affects which file the Resource Manager
  60028.        searches first when looking for a particular resource but not when
  60029.        getting indexed resources with GetIndResource.
  60030.  
  60031. If you want to find out how many resources of a given type are in a particular resource
  60032. file, you can do so as follows:  Call GetIndResource repeatedly with the index ranging
  60033. from 1 to the number of resources of that type
  60034. (CountResources(theType)). Pass each handle returned by GetIndResource to HomeResFile
  60035. and count all occurrences where the reference number returned is that of the desired
  60036. file. Be sure to start the index from 1, and to call SetResLoad(FALSE) so the resources
  60037. won’t be read in.
  60038.  
  60039. If the given index is 0 or negative, GetIndResource returns NIL, but the ResError
  60040. function will return the result code noErr. If the given index is larger than the
  60041. value CountResources(theType), GetIndResource returns NIL and the ResError function
  60042. will return the result code resNotFound. GetIndResource also returns NIL if the
  60043. resource is to be read into memory but won’t fit; in this case, ResError will return
  60044. an appropriate Operating System result code.
  60045.  
  60046. æKY Get1IndResource
  60047. æFc Resources.h
  60048. æT Function
  60049. æTN A80E
  60050. æD pascal Handle Get1IndResource(ResType theType,short index)
  60051.     = 0xA80E; 
  60052. æDT Handle myVariable = Get1IndResource((ResType) theType,(short) index);
  60053. æMM
  60054. æRI IV-15
  60055. æC 
  60056. Assembly-language note:  The macro you invoke to call Get1IndResource from
  60057.                          assembly language is named _Get1IxResource
  60058.  
  60059. Get1IndResource is the same as GetIndResource except that it searches the current
  60060. resource file only. Given an index ranging from 1 to Count1Resources(theType),
  60061. Get1IndResource returns a handle to a resource of the given type (see Count1Resources,
  60062. above). Called repeatedly over the entire range for the index, it returns handles to 
  60063. all resources of the given type in the current resource file.
  60064.  
  60065. æKY GetResource
  60066. æFc Resources.h
  60067. æT Function
  60068. æTN A9A0
  60069. æD pascal Handle GetResource(ResType theType,short theID)
  60070.     = 0xA9A0; 
  60071. æDT Handle myVariable = GetResource((ResType) theType,(short) theID);
  60072. æMM
  60073. æRT 4,154
  60074. æRI I-119, P-173
  60075. æC 
  60076. GetResource returns a handle to the resource having the given type and ID number,
  60077. reading the resource data into memory if it’s not already in memory and if you haven’t
  60078. called SetResLoad(FALSE) (see the warning above for GetIndResource). If the resource
  60079. data is already in memory, GetResource just returns the handle to the resource.
  60080.  
  60081. GetResource looks in the current resource file and all resource files opened before
  60082. it, in the reverse of the order that they were opened; the system resource file is
  60083. searched last. If it doesn’t find the resource, GetResource returns NIL and the
  60084. ResError function will return the result code resNotFound. GetResource also returns
  60085. NIL if the resource is to be read into memory but
  60086. won’t fit; in this case, ResError will return an appropriate Operating System result
  60087. code.
  60088.  
  60089. Note:  If you call GetResource with a resource type that isn’t in any open
  60090.        resource file, it returns NIL but the ResError function will return
  60091.        the result code noErr.
  60092.  
  60093. æKY Get1Resource
  60094. æFc Resources.h
  60095. æT Function
  60096. æTN A81F
  60097. æD pascal Handle Get1Resource(ResType theType,short theID)
  60098.     = 0xA81F; 
  60099. æDT Handle myVariable = Get1Resource((ResType) theType,(short) theID);
  60100. æMM
  60101. æRI IV-16
  60102. æC 
  60103. Get1Resource is the same as GetResource except that it searches the current resource
  60104. file only.
  60105.  
  60106. æKY GetNamedResource
  60107. æFc Resources.h
  60108. æT Function
  60109. æTN A9A1
  60110. æD pascal Handle GetNamedResource(ResType theType,const Str255 name)
  60111.     = 0xA9A1; 
  60112. æDT Handle myVariable = GetNamedResource((ResType) theType,(const Str255) name);
  60113. æMM
  60114. æRI I-119
  60115. æC  
  60116. GetNamedResource is the same as GetResource (above) except that you pass a resource
  60117. name instead of an ID number.
  60118.  
  60119. æKY Get1NamedResource
  60120. æFc Resources.h
  60121. æT Function
  60122. æTN A820
  60123. æD pascal Handle Get1NamedResource(ResType theType,const Str255 name)
  60124.     = 0xA820; 
  60125. æDT Handle myVariable = Get1NamedResource((ResType) theType,(const Str255) name);
  60126. æMM
  60127. æRI IV-15
  60128. æC  
  60129. Get1NamedResource is the same as GetNamedResource except that it searches the current
  60130. resource file only.
  60131.  
  60132. æKY LoadResource
  60133. æFc Resources.h
  60134. æT Function
  60135. æTN A9A2
  60136. æD pascal void LoadResource(Handle theResource)
  60137.     = 0xA9A2; 
  60138. æDT LoadResource((Handle) theResource);
  60139. æMM
  60140. æRI I-119
  60141. æC 
  60142. Given a handle to a resource (returned by GetIndResource, GetResource, or GetNamedResource),
  60143. LoadResource reads that resource into memory. It does nothing if the resource is
  60144. already in memory or if the given handle isn’t a handle to a resource; in the latter
  60145. case, the ResError function will return the result code resNotFound. Call this procedure
  60146. if you want to access the data for a resource through its handle and either you’ve
  60147. called SetResLoad(FALSE) or the resource is purgeable.
  60148.  
  60149. If you’ve changed the resource data for a purgeable resource and the resource is
  60150. purged before being written to the resource file, the changes will be lost; LoadResource
  60151. will reread the original resource from the resource file. See the descriptions of
  60152. ChangedResource and SetResPurge for information about how to ensure that changes made
  60153. to purgeable resources will be written to the resource file.
  60154.  
  60155. Assembly-language note:  LoadResource preserves all registers.
  60156.  
  60157. æKY ReleaseResource
  60158. æFc Resources.h
  60159. æT Function
  60160. æTN A9A3
  60161. æD pascal void ReleaseResource(Handle theResource)
  60162.     = 0xA9A3; 
  60163. æDT ReleaseResource((Handle) theResource);
  60164. æMM
  60165. æRT 1,180
  60166. æRI I-120, P-103, 179
  60167. æC  
  60168. Given a handle to a resource, ReleaseResource releases the memory occupied by the
  60169. resource data, if any, and replaces the handle to that resource in the resource map
  60170. with NIL (see Figure 9). The given handle will no longer be recognized as a handle to
  60171. a resource; if the Resource Manager is subsequently called to get the released resource,
  60172. a new handle will be allocated. Use this procedure only after you’re completely
  60173. through with a resource.
  60174.  
  60175. •••Refer to Figure 9.•••
  60176.  
  60177. Figure 9–ReleaseResource and DetachResource
  60178.  
  60179. If the given handle isn’t a handle to a resource, ReleaseResource will do nothing and
  60180. the ResError function will return the result code resNotFound. ReleaseResource won’t
  60181. let you release a resource whose resChanged attribute has been set; however, ResError
  60182. will still return noErr.
  60183.  
  60184. æKY DetachResource
  60185. æFc Resources.h
  60186. æT Function
  60187. æTN A992
  60188. æD pascal void DetachResource(Handle theResource)
  60189.     = 0xA992; 
  60190. æDT DetachResource((Handle) theResource);
  60191. æRT 180
  60192. æRI I-120
  60193. æC  
  60194. Given a handle to a resource, DetachResource replaces the handle to that resource in
  60195. the resource map with NIL (see Figure 9 above). The given handle will no longer be
  60196. recognized as a handle to a resource; if the Resource Manager is subsequently called
  60197. to get the detached resource, a new handle will be allocated.
  60198.  
  60199. DetachResource is useful if you want the resource data to be accessed only by yourself
  60200. through the given handle and not by the Resource Manager. DetachResource is also
  60201. useful in the unusual case that you don’t want a resource to be released when a
  60202. resource file is closed. To copy a resource, you can call DetachResource followed by
  60203. AddResource (with a new resource ID).
  60204.  
  60205. If the given handle isn’t a handle to a resource, DetachResource will do nothing and
  60206. the ResError function will return the result code resNotFound. DetachResource won’t
  60207. let you detach a resource whose resChanged attribute has been set; however, ResError
  60208. will still return noErr.
  60209.  
  60210. •••Refer to Figure 9.•••
  60211.  
  60212. Figure 9–ReleaseResource and DetachResource
  60213.  
  60214. æKY UniqueID
  60215. æFc Resources.h
  60216. æT Function
  60217. æTN A9C1
  60218. æD pascal short UniqueID(ResType theType)
  60219.     = 0xA9C1; 
  60220. æDT short myVariable = UniqueID((ResType) theType);
  60221. æRI I-121
  60222. æC 
  60223. UniqueID returns an ID number greater than 0 that isn’t currently assigned to any
  60224. resource of the given type in any open resource file. Using this number when you add
  60225. a new resource to a resource file ensures that you won’t duplicate a resource ID and
  60226. override an existing resource.
  60227.  
  60228. Warning:  It’s possible that UniqueID will return an ID in the range reserved
  60229.           for system resources (0 to 127). You should check that the ID
  60230.           returned is greater than 127; if it isn’t, call UniqueID again.
  60231.  
  60232. æKY Unique1ID
  60233. æFc Resources.h
  60234. æT Function
  60235. æTN A810
  60236. æD pascal short Unique1ID(ResType theType)
  60237.     = 0xA810; 
  60238. æDT short myVariable = Unique1ID((ResType) theType);
  60239. æRT 198
  60240. æRI IV-16
  60241. æC  
  60242. Unique1ID is the same as UniqueID except that the ID number it returns is unique only
  60243. with respect to resources in the current resource file.
  60244.  
  60245. æKY GetResAttrs
  60246. æFc Resources.h
  60247. æT Function
  60248. æTN A9A6
  60249. æD pascal short GetResAttrs(Handle theResource)
  60250.     = 0xA9A6; 
  60251. æDT short myVariable = GetResAttrs((Handle) theResource);
  60252. æRI I-121
  60253. æC 
  60254. Given a handle to a resource, GetResAttrs returns the resource attributes for the
  60255. resource. (Resource attributes are described above under “Resource References”.) If
  60256. the given handle isn’t a handle to a resource, GetResAttrs will do nothing and the
  60257. ResError function will return the result code resNotFound.
  60258.  
  60259. æKY GetResInfo
  60260. æFc Resources.h
  60261. æT Function
  60262. æTN A9A8
  60263. æD pascal void GetResInfo(Handle theResource,short *theID,ResType *theType,
  60264.     Str255 name)
  60265.     = 0xA9A8; 
  60266. æDT GetResInfo((Handle) theResource,(short *) theID,(ResType *) theType,()
  60267.     Str255 name);
  60268. æRI I-113, 121
  60269. æC  
  60270. Given a handle to a resource, GetResInfo returns the ID number, type, and name of the
  60271. resource. If the given handle isn’t a handle to a resource, GetResInfo will do nothing
  60272. and the ResError function will return the result code resNotFound.
  60273.  
  60274. æKY SetResInfo
  60275. æFc Resources.h
  60276. æT Function
  60277. æTN A9A9
  60278. æD pascal void SetResInfo(Handle theResource,short theID,const Str255 name)
  60279.     = 0xA9A9; 
  60280. æDT SetResInfo((Handle) theResource,(short) theID,(const Str255) name);
  60281. æMM
  60282. æRI I-122
  60283. æC  
  60284. Except for UpdateResFile and WriteResource, all the routines described below change
  60285. the resource map in memory and not the resource file itself.
  60286.  
  60287. Given a handle to a resource, SetResInfo changes the ID number and name of the resource
  60288. to the given ID number and name.
  60289.  
  60290. Assembly-language note:  If you pass 0 for the name parameter, the name will
  60291.                          not be changed.
  60292.  
  60293. Warning:  It’s a dangerous practice to change the ID number and name of a
  60294.           system resource, because other applications may already access the
  60295.           resource and may no longer work properly.
  60296.  
  60297. The change will be written to the resource file when the file is updated if you
  60298. follow SetResInfo with a call to ChangedResource.
  60299.  
  60300. Warning:  Even if you don’t call ChangedResource for this resource, the change
  60301.           may be written to the resource file when the file is updated. If
  60302.           you’ve ever called ChangedResource for any resource in the file, or
  60303.           if you’ve added or removed a resource, the Resource Manager will
  60304.           write out the entire resource map when it updates the file, so all
  60305.           changes made to resource information in the map will become permanent.
  60306.           If you want any of the changes to be temporary, you’ll have to
  60307.           restore the original information before the file is updated.
  60308. _______________________________________________________________________________
  60309.  
  60310. »SetResInfo does nothing in the following cases:
  60311.  
  60312.   •  The given handle isn’t a handle to a resource. The ResError function will
  60313.      return the result code resNotFound.
  60314.   •  The resource map becomes too large to fit in memory (which can happen if
  60315.      a name is passed) or the modified resource file can’t be written out to
  60316.      the disk. ResError will return an appropriate Operating System result code.
  60317.   •  The resProtected attribute for the resource is set. ResError will,
  60318.      however, return the result code noErr.
  60319.  
  60320. æKY AddResource
  60321. æFc Resources.h
  60322. æT Function
  60323. æTN A9AB
  60324. æD pascal void AddResource(Handle theResource,ResType theType,short theID,
  60325.     const Str255 name)
  60326.     = 0xA9AB; 
  60327. æDT AddResource((Handle) theResource,(ResType) theType,(short) theID,(
  60328.     const) Str255 name);
  60329. æRI I-124
  60330. æC  
  60331. Except for UpdateResFile and WriteResource, all the routines described below change
  60332. the resource map in memory and not the resource file itself.
  60333.  
  60334. Given a handle to data in memory (not a handle to an existing resource), AddResource
  60335. adds to the current resource file a resource reference that points to the data. It
  60336. sets the resChanged attribute for the resource, so the data will be written to the
  60337. resource file when the file is updated or when WriteResource is called. If the given
  60338. handle is empty, zero-length resource data will be written.
  60339.  
  60340. Note:  To make a copy of an existing resource, call DetachResource before
  60341.        calling AddResource. To add the same data to several different resource
  60342.        files, call the Operating System Utility function HandToHand to
  60343.        duplicate the handle for each resource reference.
  60344.  
  60345. AddResource does nothing in the following cases:
  60346.  
  60347.   •  The given handle is NIL or is already a handle to an existing resource
  60348.    . The ResError function will return the result code addResFailed.
  60349.   •  The resource map becomes too large to fit in memory or the modified
  60350.      resource file can’t be written out to the disk. ResError will return an
  60351.      appropriate Operating System result code. (The warning under
  60352.      ChangedResource above concerning the resChanged attribute also applies
  60353.      to AddResource.)
  60354.  
  60355. Warning:  AddResource doesn’t verify whether the resource ID you pass is
  60356.           already assigned to another resource of the same type; be sure to
  60357.           call UniqueID before adding a resource.
  60358.  
  60359. æKY SizeResource
  60360. æFc Resources.h
  60361. æT Function
  60362. æTN A9A5
  60363. æD pascal long SizeResource(Handle theResource)
  60364.     = 0xA9A5; 
  60365. æDT long myVariable = SizeResource((Handle) theResource);
  60366. æRI I-121
  60367. æC 
  60368. Assembly-language note:  The macro you invoke to call SizeResource from
  60369.                          assembly language is named _SizeRsrc.
  60370.  
  60371. Given a handle to a resource, SizeResource returns the size in bytes of the resource
  60372. in the resource file. If the given handle isn’t a handle to a resource, SizeResource
  60373. will return –1 and the ResError function will return the result code resNotFound.
  60374. It’s a good idea to call SizeResource and ensure that sufficient space is available
  60375. before reading a resource into memory.
  60376.  
  60377. æKY MaxSizeRsrc
  60378. æFc Resources.h
  60379. æT Function
  60380. æTN A821
  60381. æD pascal long MaxSizeRsrc(Handle theResource)
  60382.     = 0xA821; 
  60383. æDT long myVariable = MaxSizeRsrc((Handle) theResource);
  60384. æRI IV-16
  60385. æC 
  60386. MaxSizeRsrc is similar to SizeResource except that it does not cause the disk to be
  60387. read; instead it determines the size (in bytes) of the resource from the offsets
  60388. found in the resource map.
  60389.  
  60390. Since MaxSizeRsrc does not read from the disk, it returns only the maximum size of
  60391. the resource. In other words, you can count on the resource not being larger than the
  60392. number of bytes reported by MaxSizeRsrc; it’s possible, however, that the resource is
  60393. actually smaller than the resource map indicates (because the file has not yet been
  60394. compacted). If called after UpdateResFile, MaxSizeRsrc will return the correct size
  60395. of the resource.
  60396.  
  60397. æKY RsrcMapEntry
  60398. æFc Resources.h
  60399. æT Function
  60400. æTN A9C5
  60401. æD pascal long RsrcMapEntry(Handle theResource)
  60402.     = 0xA9C5; 
  60403. æDT long myVariable = RsrcMapEntry((Handle) theResource);
  60404. æRI IV-16
  60405. æC 
  60406. RsrcMapEntry provides a way to access the resource references in the resource map.
  60407. Given a handle to a resource, RsrcMapEntry returns the offset of the resource’s
  60408. reference from the beginning of the resource map. (For more information on resource
  60409. references and the structure of a resource map, see the section “Format of a Resource
  60410. File” in the Resource Manager chapter.) If it doesn’t find the resource, RsrcMapEntry
  60411. returns NIL and the ResError function will return the result code resNotFound. If you
  60412. pass it a NIL handle, RsrcMapEntry will return garbage but ResError will return the
  60413. result code noErr.
  60414.  
  60415. Warning:  Since routines are provided for opening, accessing, and changing
  60416.           resources, there’s really no reason to access resources directly.
  60417.           To avoid damaging the resource file, you should be extremely careful
  60418.           if you use RsrcMapEntry.
  60419.  
  60420. æKY SetResAttrs
  60421. æFc Resources.h
  60422. æT Function
  60423. æTN A9A7
  60424. æD pascal void SetResAttrs(Handle theResource,short attrs)
  60425.     = 0xA9A7; 
  60426. æDT SetResAttrs((Handle) theResource,(short) attrs);
  60427. æRT 78
  60428. æRI I-122, N78-2
  60429. æC  
  60430. Except for UpdateResFile and WriteResource, all the routines described below change
  60431. the resource map in memory and not the resource file itself.
  60432.  
  60433. Given a handle to a resource, SetResAttrs sets the resource attributes for the resource
  60434. to attrs. (Resource attributes are described above under “Resource References”.) The
  60435. resProtected attribute takes effect immediately; the others take effect the next time
  60436. the resource is read in.
  60437.  
  60438. Warning:  Do not use SetResAttrs to set the resChanged attribute; you must
  60439.           call ChangedResource instead. Be sure that the attrs parameter
  60440.           passed to SetResAttrs doesn’t change the current setting of this
  60441.           attribute; to determine the current setting, first call GetResAttrs.
  60442.  
  60443. The attributes set with SetResAttrs will be written to the resource file when the
  60444. file is updated if you follow SetResAttrs with a call to ChangedResource. However,
  60445. even if you don’t call ChangedResource for this resource, the change may be written
  60446. to the resource file when the file is updated. See the last warning for SetResInfo
  60447. (above).
  60448.  
  60449. •••Refer to Technical Note #78:•••
  60450.  
  60451. If the given handle isn’t a handle to a resource, SetResAttrs will do nothing and the
  60452. ResError function will return the result code resNotFound.
  60453.  
  60454. æKY ChangedResource
  60455. æFc Resources.h
  60456. æT Function
  60457. æTN A9AA
  60458. æD pascal void ChangedResource(Handle theResource)
  60459.     = 0xA9AA; 
  60460. æDT ChangedResource((Handle) theResource);
  60461. æMM
  60462. æRT 188
  60463. æRI I-123
  60464. æC  
  60465. Except for UpdateResFile and WriteResource, all the routines described below change
  60466. the resource map in memory and not the resource file itself.
  60467.  
  60468. Call ChangedResource after changing either the information about a resource in the
  60469. resource map (as described above under SetResInfo and SetResAttrs) or the resource
  60470. data for a resource, if you want the change to be permanent. Given a handle to a
  60471. resource, ChangedResource sets the resChanged attribute for the resource. This attribute
  60472. tells the Resource Manager to do both of the following:
  60473.  
  60474. •  write the resource data for the resource to the resource file when the file
  60475.    is updated or when WriteResource is called
  60476. •  write the entire resource map to the resource file when the file is updated
  60477.  
  60478. Warning:  If you change information in the resource map with SetResInfo or
  60479.           SetResAttrs and then call ChangedResource, remember that not only
  60480.           the resource map but also the resource data will be written out when
  60481.           the resource file is updated.
  60482.  
  60483. To change the resource data for a purgeable resource and make the change permanent,
  60484. you have to take special precautions to ensure that the resource
  60485. won’t be purged while you’re changing it. You can make the resource temporarily
  60486. unpurgeable and then write it out with WriteResource before making it purgeable
  60487. again. You have to use the Memory Manager procedures HNoPurge and HPurge to make the
  60488. resource unpurgeable and purgeable; SetResAttrs can’t be used because it won’t take
  60489. effect immediately. For example:
  60490.  
  60491.    myHndl := GetResource(type,ID);    {or LoadResource(myHndl) if }
  60492.                                       { you've gotten it previously}
  60493.   HNoPurge(myHndl);                   {make it unpurgeable}
  60494.   . . .                               {make the changes here}
  60495.   ChangedResource(myHndl);            {mark it changed}
  60496.   WriteResource(myHndl);              {write it out}
  60497.   HPurge(myHndl)                      {make it purgeable again}
  60498.  
  60499. Or, instead of calling WriteResource to write the data out immediately, you can call
  60500. SetResPurge(TRUE) before making any changes to purgeable resource data.
  60501.  
  60502. ChangedResource does nothing in the following cases:
  60503.  
  60504.   •  The given handle isn’t a handle to a resource. The ResError function will
  60505.      return the result code resNotFound.
  60506.   •  The modified resource file can’t be written out to the disk. ResError will
  60507.      return an appropriate Operating System result code.
  60508.   •  The resProtected attribute for the modified resource is set. ResError will,
  60509.      however, return the result code noErr.
  60510.  
  60511. •••Refer to Technical Note #188:•••
  60512.  
  60513. Warning:  Be aware that if the modified file can’t be written out to the disk,
  60514.           the resChanged attribute won’t be set. This means that when
  60515.           WriteResource is called, it won’t know that the resource file has
  60516.           been changed; it won’t write out the modified file and no error will
  60517.           be returned. For this reason, always check to see that
  60518.           ChangedResource returns noErr.
  60519.  
  60520. æKY RmveResource
  60521. æFc Resources.h
  60522. æT Function
  60523. æTN A9AD
  60524. æD pascal void RmveResource(Handle theResource)
  60525.     = 0xA9AD; 
  60526. æDT RmveResource((Handle) theResource);
  60527. æMM
  60528. æRI I-113, 124
  60529. æC  
  60530. Except for UpdateResFile and WriteResource, all the routines described below change
  60531. the resource map in memory and not the resource file itself.
  60532.  
  60533. Given a handle to a resource in the current resource file, RmveResource removes its
  60534. resource reference. The resource data will be removed from the resource file when the
  60535. file is updated.
  60536.  
  60537. Note:  RmveResource doesn’t release the memory occupied by the resource data;
  60538.        to do that, call the Memory Manager procedure DisposHandle after calling
  60539.        RmveResource.
  60540.  
  60541. If the resProtected attribute for the resource is set or if the given handle isn’t a
  60542. handle to a resource in the current resource file, RmveResource will do nothing and
  60543. the ResError function will return the result code rmvResFailed.
  60544.  
  60545. æKY UpdateResFile
  60546. æFc Resources.h
  60547. æT Function
  60548. æTN A999
  60549. æD pascal void UpdateResFile(short refNum)
  60550.     = 0xA999; 
  60551. æDT UpdateResFile((short) refNum);
  60552. æRT 116, 188
  60553. æRI I-125, N116-1
  60554. æC 
  60555. Given the reference number of a resource file, UpdateResFile does the following:
  60556.  
  60557.   •  Changes, adds, or removes resource data in the file as appropriate to
  60558.      match the map. Remember that changed resource data is written out only if
  60559.      you called ChangedResource (and the call was successful). UpdateResFile
  60560.      calls WriteResource to write out changed or added resources.
  60561.   •  Compacts the resource file, closing up any empty space created when a
  60562.      resource was removed, made smaller, or made larger. (If the size of a
  60563.      changed resource is greater than its original size in the resource file,
  60564.      it’s written at the end of the file rather than at its original location;
  60565.      the space occupied by the original is then compacted.) The actual size of
  60566.      the resource file will be adjusted when a resource is removed or made
  60567.      larger, but not when a resource is made smaller.
  60568.   •  Writes out the resource map of the resource file, if you ever called
  60569.      ChangedResource for any resource in the file or if you added or removed
  60570.      a resource. All changes to resource information in the map will become
  60571.      permanent as a result of this, so if you want any such changes to be
  60572.      temporary, you must restore the original information before calling
  60573.      UpdateResFile.
  60574.  
  60575. If there’s no open resource file with the given reference number, UpdateResFile will
  60576. do nothing and the ResError function will return the result code resFNotFound. A
  60577. refNum of 0 represents the system resource file.
  60578.  
  60579. The CloseResFile procedure calls UpdateResFile before it closes the resource file, so
  60580. you only need to call UpdateResFile yourself if you want to update the file without
  60581. closing it.
  60582.  
  60583. æKY getnamedresource
  60584. æFc Resources.h
  60585. æT Function
  60586. æD Handle getnamedresource(ResType theType,char *name); 
  60587. æDT Handle myVariable = getnamedresource((ResType) theType,(char *) name);
  60588. æMM
  60589. æRI I-119
  60590. æC  
  60591. GetNamedResource is the same as GetResource (above) except that you pass a resource
  60592. name instead of an ID number.
  60593.  
  60594. æKY WriteResource
  60595. æFc Resources.h
  60596. æT Function
  60597. æTN A9B0
  60598. æD pascal void WriteResource(Handle theResource)
  60599.     = 0xA9B0; 
  60600. æDT WriteResource((Handle) theResource);
  60601. æRT 111, 188 
  60602. æRI I-125, N54-1, N63-1
  60603. æC 
  60604. Given a handle to a resource, WriteResource checks the resChanged attribute for that
  60605. resource and, if it’s set (which it will be if you called ChangedResource or AddResource
  60606. successfully), writes its resource data to the resource file and clears its resChanged
  60607. attribute.
  60608.  
  60609. Warning:  Be aware that ChangedResource and AddResource determine whether the
  60610.           modified file can be written out to the disk; if it can’t, the
  60611.           resChanged attribute won’t be set and WriteResource will be unaware
  60612.           of the modifications. For this reason, always verify that
  60613.           ChangedResource and AddResource return noErr.
  60614.  
  60615. If the resource is purgeable and has been purged, zero-length resource data will be
  60616. written. WriteResource does nothing if the resProtected attribute for the resource is
  60617. set or if the resChanged attribute isn’t set; in both cases, however, the ResError
  60618. function will return the result code noErr. If the given handle isn’t a handle to a
  60619. resource, WriteResource will do nothing and the ResError function will return the
  60620. result code resNotFound.
  60621.  
  60622. Since the resource file is updated when the application terminates or when you call
  60623. UpdateResFile (or CloseResFile, which calls UpdateResFile), you only need to call
  60624. WriteResource if you want to write out just one or a few resources immediately.
  60625.  
  60626. Warning:  The maximum size for a resource to be written to a resource file is
  60627.           32K bytes.
  60628.  
  60629. æKY SetResPurge
  60630. æFc Resources.h
  60631. æT Function
  60632. æTN A993
  60633. æD pascal void SetResPurge(Boolean install)
  60634.     = 0xA993; 
  60635. æDT SetResPurge((Boolean) install);
  60636. æRT 111
  60637. æRI I-126, N111
  60638. æC  
  60639. SetResPurge(TRUE) sets a “hook” in the Memory Manager such that before purging data
  60640. specified by a handle, the Memory Manager will first pass the handle to the Resource
  60641. Manager. The Resource Manager will determine whether the handle is that of a resource
  60642. in the application heap and, if so, will call WriteResource to write the resource
  60643. data for that resource to the resource file if its resChanged attribute is set (see
  60644. ChangedResource and WriteResource). SetResPurge(FALSE) restores the normal state,
  60645. clearing the hook so that the Memory Manager will once again purge without checking
  60646. with the Resource Manager.
  60647.  
  60648. SetResPurge(TRUE) is useful in applications that modify purgeable resources. You
  60649. still have to make the resources temporarily unpurgeable while making the changes, as
  60650. shown in the description of ChangedResource, but you can set the purge hook instead
  60651. of writing the data out immediately with WriteResource. Notice that you won’t know
  60652. exactly when the resources are being written out; most applications will want more
  60653. control than this. If you wish, you can set your own such hook; for details, refer to
  60654. the section “Memory Manager Data Structures” in the Memory Manager chapter.
  60655.  
  60656. æKY get1namedresource
  60657. æFc Resources.h
  60658. æT Function
  60659. æD Handle get1namedresource(ResType theType,char *name); 
  60660. æDT Handle myVariable = get1namedresource((ResType) theType,(char *) name);
  60661. æMM
  60662. æRI IV-15
  60663. æC  
  60664. Get1NamedResource is the same as GetNamedResource except that it searches the current
  60665. resource file only.
  60666.  
  60667. æKY GetResFileAttrs
  60668. æFc Resources.h
  60669. æT Function
  60670. æTN A9F6
  60671. æD pascal short GetResFileAttrs(short refNum)
  60672.     = 0xA9F6; 
  60673. æDT short myVariable = GetResFileAttrs((short) refNum);
  60674. æRI I-113, 127
  60675. æC 
  60676. Given the reference number of a resource file, GetResFileAttrs returns the resource
  60677. file attributes for the file. If there’s no resource file with the given reference
  60678. number, GetResFileAttrs will do nothing and the ResError function will return the
  60679. result code resFNotFound. A refNum of 0 represents the system resource file.
  60680.  
  60681. æKY SetResFileAttrs
  60682. æFc Resources.h
  60683. æT Function
  60684. æTN A9F7
  60685. æD pascal void SetResFileAttrs(short refNum,short attrs)
  60686.     = 0xA9F7; 
  60687. æDT SetResFileAttrs((short) refNum,(short) attrs);
  60688. æRI I-127
  60689. æC 
  60690. Given the reference number of a resource file, SetResFileAttrs sets the resource file
  60691. attributes of the file to attrs. If there’s no resource file with the given reference
  60692. number, SetResFileAttrs will do nothing but the ResError function will return the
  60693. result code noErr. A refNum of 0 represents the system resource file, but you shouldn’t
  60694. change its resource file attributes.
  60695.  
  60696. æKY OpenRFPerm
  60697. æFc Resources.h
  60698. æT Function
  60699. æTN A9C4
  60700. æD pascal short OpenRFPerm(const Str255 fileName,short vRefNum,char permission)
  60701.     = 0xA9C4; 
  60702. æDT short myVariable = OpenRFPerm((const Str255) fileName,(short) vRefNum,(char) permission);
  60703. æMM
  60704. æRT 116, 185
  60705. æRI IV-17, N116-2
  60706. æC 
  60707. OpenRFPerm is similar to OpenResFile except that it allows you to specify the read/write
  60708. permission of the resource file the first time it is opened; OpenRFPerm also lets you
  60709. specify in vRefNum the directory or volume on which the file is located (see the File
  60710. Manager chapter for more details on directories). Permission can have any of the
  60711. values that you would pass to the File Manager; these values are given in “Low-Level
  60712. File Manager Routines” in the File Manager chapter.
  60713.  
  60714. OpenRFPerm, like OpenResFile, will not open the specified file twice; it simply
  60715. returns the reference number already assigned to the file. In other words, OpenRFPerm
  60716. cannot be used to open a second access path to a resource file nor can it be used to
  60717. change the permission of an already open file. Since OpenRFPerm gives no indication
  60718. of whether the file was already open, there’s no way to tell whether the file’s open
  60719. permission is what you specified or what was specified by an earlier call.
  60720.  
  60721. •••Refer to Technical Note #185:•••
  60722.  
  60723. Note:  The shared read/write permission described in the File Manager chapter
  60724.        has no effect with OpenRFPerm since the Resource Manager is unable to
  60725.        deal with a portion of a resource file.
  60726.  
  60727. æKY RGetResource
  60728. æFc Resources.h
  60729. æT Function
  60730. æTN A80C
  60731. æD pascal Handle RGetResource(ResType theType,short theID)
  60732.     = 0xA80C; 
  60733. æDT Handle myVariable = RGetResource((ResType) theType,(short) theID);
  60734. æMM
  60735. æRI V-30
  60736. æC 
  60737. RGetResource is identical in function to GetResource except that it looks through the
  60738. chain of open resource files for the specified resource, and if it doesn’t find it
  60739. there, it looks in the ROM resources.
  60740.  
  60741. Note:  With System file version 4.1 or later, RGetResource will also work on
  60742.        the Macintosh Plus.
  60743.  
  60744. æKY HOpenResFile
  60745. æFc Resources.h
  60746. æT Function
  60747. æD pascal short HOpenResFile(short vRefNum,long dirID,const Str255 fileName,
  60748.     char permission); 
  60749. æDT short myVariable = HOpenResFile((short) vRefNum,(long) dirID,(const Str255) fileName,()
  60750.     char permission);
  60751. æRT 214
  60752. æC 
  60753. The HOpenResFile function opens an existing resource file in the directory
  60754. specified by the values of vRefNum and dirID and returns the reference number of
  60755. the resource file.  If the reference number is -1, you should call _ResError to
  60756. check for errors.  This function also lets you open a resource file without
  60757. creating a working directory.
  60758.  
  60759. æKY HCreateResFile
  60760. æFc Resources.h
  60761. æT Function
  60762. æD pascal void HCreateResFile(short vRefNum,long dirID,const Str255 fileName); 
  60763. æDT HCreateResFile((short) vRefNum,(long) dirID,(const Str255) fileName);
  60764. æRT 214
  60765. æC 
  60766. The HCreateResFile procedure creates a new resource file with the name given by
  60767. the string fileName, in the directory specified by the values of vRefNum and
  60768. dirID.  You should call _ResError to check for errors.
  60769.  
  60770. æKY openrfperm
  60771. æFc Resources.h
  60772. æT Function
  60773. æD short openrfperm(char *fileName,short vRefNum,char permission); 
  60774. æDT short myVariable = openrfperm((char *) fileName,(short) vRefNum,(char) permission);
  60775. æMM
  60776. æRT 116, 185
  60777. æRI IV-17
  60778. æC 
  60779. OpenRFPerm is similar to OpenResFile except that it allows you to specify the read/write
  60780. permission of the resource file the first time it is opened; OpenRFPerm also lets you
  60781. specify in vRefNum the directory or volume on which the file is located (see the File
  60782. Manager chapter for more details on directories). Permission can have any of the
  60783. values that you would pass to the File Manager; these values are given in “Low-Level
  60784. File Manager Routines” in the File Manager chapter.
  60785.  
  60786. OpenRFPerm, like OpenResFile, will not open the specified file twice; it simply
  60787. returns the reference number already assigned to the file. In other words, OpenRFPerm
  60788. cannot be used to open a second access path to a resource file nor can it be used to
  60789. change the permission of an already open file. Since OpenRFPerm gives no indication
  60790. of whether the file was already open, there’s no way to tell whether the file’s open
  60791. permission is what you specified or what was specified by an earlier call.
  60792.  
  60793. •••Refer to Technical Note #185:•••
  60794.  
  60795. Note:  The shared read/write permission described in the File Manager chapter
  60796.        has no effect with OpenRFPerm since the Resource Manager is unable to
  60797.        deal with a portion of a resource file.
  60798.  
  60799. æKY openresfile
  60800. æFc Resources.h
  60801. æT Function
  60802. æD short openresfile(char *fileName); 
  60803. æDT short myVariable = openresfile((char *) fileName);
  60804. æMM
  60805. æRT 46, 46,74, 78, 101, 185, 214,232 
  60806. æRI I-115, N46-1, N78-1, 2, N101-2
  60807. æC 
  60808. When calling the CreateResFile or OpenResFile routine, described below, you specify a
  60809. resource file by its file name; the routine assumes that the file has a version
  60810. number of 0 and is on the default volume. (Version numbers and volumes are described
  60811. in the File Manager chapter.) If you want the routine to apply to a file on another
  60812. volume, just set the default volume to that volume.
  60813.  
  60814. •••Refer to Technical Notes #101 & #214:•••
  60815.  
  60816. OpenResFile opens the resource file having the given name and makes it the current
  60817. resource file. It reads the resource map from the file into memory and returns a
  60818. reference number for the file. It also reads in every resource whose resPreload
  60819. attribute is set. If the resource file is already open, it doesn’t make it the current
  60820. resource file; it simply returns the reference number.
  60821.  
  60822. Note:  You don’t have to call OpenResFile to open the system resource file
  60823.        or the application’s resource file, because they’re opened when the
  60824.        system and the application start up, respectively. To get the reference
  60825.        number of the application’s resource file, you can call CurResFile after
  60826.        the application starts up (before you open any other resource file).
  60827.  
  60828. If the file can’t be opened, OpenResFile will return –1 and the ResError function
  60829. will return an appropriate Operating System result code. For example, an error occurs
  60830. if there’s no resource file with the given name.
  60831.  
  60832. •••Refer to Technical Notes #74 & #232:•••
  60833.  
  60834. Note:  To open a resource file simply for block-level operations such as
  60835.        copying files (without reading the resource map into memory), you
  60836.        can call the File Manager function OpenRF.
  60837.  
  60838. Assembly-language note:  A handle to the resource map of the most recently
  60839.                          opened resource file is stored in the global variable
  60840.                          TopMapHndl.
  60841.  
  60842. æKY createresfile
  60843. æFc Resources.h
  60844. æT Function
  60845. æD void createresfile(char *fileName); 
  60846. æDT createresfile((char *) fileName);
  60847. æRT 101, 214
  60848. æRI I-114, N101
  60849. æC  
  60850. When calling the CreateResFile or OpenResFile routine, described below, you specify a
  60851. resource file by its file name; the routine assumes that the file has a version
  60852. number of 0 and is on the default volume. (Version numbers and volumes are described
  60853. in the File Manager chapter.) If you want the routine to apply to a file on another
  60854. volume, just set the default volume to that volume.
  60855.  
  60856. •••Refer to Technical Notes #101 & #214:•••
  60857.  
  60858. CreateResFile creates a resource file containing no resource data. If there’s no file
  60859. at all with the given name, it also creates an empty data fork for the file. If
  60860. there’s already a resource file with the given name (that is, a resource fork that
  60861. isn’t empty), CreateResFile will do nothing and the ResError function will return an
  60862. appropriate Operating System result code.
  60863.  
  60864. Note:  Before you can work with the resource file, you need to open it with
  60865.        OpenResFile.
  60866.  
  60867. æKY getresinfo
  60868. æFc Resources.h
  60869. æT Function
  60870. æD void getresinfo(Handle theResource,short *theID,ResType *theType,char *name); 
  60871. æDT getresinfo((Handle) theResource,(short *) theID,(ResType *) theType,(char *) name);
  60872. æRI I-113, 121
  60873. æC  
  60874. Given a handle to a resource, GetResInfo returns the ID number, type, and name of the
  60875. resource. If the given handle isn’t a handle to a resource, GetResInfo will do nothing
  60876. and the ResError function will return the result code resNotFound.
  60877.  
  60878. æKY setresinfo
  60879. æFc Resources.h
  60880. æT Function
  60881. æD void setresinfo(Handle theResource,short theID,char *name); 
  60882. æDT setresinfo((Handle) theResource,(short) theID,(char *) name);
  60883. æMM
  60884. æRI I-122
  60885. æC  
  60886. Except for UpdateResFile and WriteResource, all the routines described below change
  60887. the resource map in memory and not the resource file itself.
  60888.  
  60889. Given a handle to a resource, SetResInfo changes the ID number and name of the resource
  60890. to the given ID number and name.
  60891.  
  60892. Assembly-language note:  If you pass 0 for the name parameter, the name will
  60893.                          not be changed.
  60894.  
  60895. Warning:  It’s a dangerous practice to change the ID number and name of a
  60896.           system resource, because other applications may already access the
  60897.           resource and may no longer work properly.
  60898.  
  60899. The change will be written to the resource file when the file is updated if you
  60900. follow SetResInfo with a call to ChangedResource.
  60901.  
  60902. Warning:  Even if you don’t call ChangedResource for this resource, the change
  60903.           may be written to the resource file when the file is updated. If
  60904.           you’ve ever called ChangedResource for any resource in the file, or
  60905.           if you’ve added or removed a resource, the Resource Manager will
  60906.           write out the entire resource map when it updates the file, so all
  60907.           changes made to resource information in the map will become permanent.
  60908.           If you want any of the changes to be temporary, you’ll have to
  60909.           restore the original information before the file is updated.
  60910. _______________________________________________________________________________
  60911.  
  60912. »SetResInfo does nothing in the following cases:
  60913.  
  60914.   •  The given handle isn’t a handle to a resource. The ResError function will
  60915.      return the result code resNotFound.
  60916.   •  The resource map becomes too large to fit in memory (which can happen if
  60917.      a name is passed) or the modified resource file can’t be written out to
  60918.      the disk. ResError will return an appropriate Operating System result code.
  60919.   •  The resProtected attribute for the resource is set. ResError will,
  60920.      however, return the result code noErr.
  60921.  
  60922. æKY addresource
  60923. æFc Resources.h
  60924. æT Function
  60925. æD void addresource(Handle theResource,ResType theType,short theID,char *name); 
  60926. æDT addresource((Handle) theResource,(ResType) theType,(short) theID,(char *) name);
  60927. æRI I-124
  60928. æC  
  60929. Except for UpdateResFile and WriteResource, all the routines described below change
  60930. the resource map in memory and not the resource file itself.
  60931.  
  60932. Given a handle to data in memory (not a handle to an existing resource), AddResource
  60933. adds to the current resource file a resource reference that points to the data. It
  60934. sets the resChanged attribute for the resource, so the data will be written to the
  60935. resource file when the file is updated or when WriteResource is called. If the given
  60936. handle is empty, zero-length resource data will be written.
  60937.  
  60938. Note:  To make a copy of an existing resource, call DetachResource before
  60939.        calling AddResource. To add the same data to several different resource
  60940.        files, call the Operating System Utility function HandToHand to
  60941.        duplicate the handle for each resource reference.
  60942.  
  60943. AddResource does nothing in the following cases:
  60944.  
  60945.   •  The given handle is NIL or is already a handle to an existing resource
  60946.    . The ResError function will return the result code addResFailed.
  60947.   •  The resource map becomes too large to fit in memory or the modified
  60948.      resource file can’t be written out to the disk. ResError will return an
  60949.      appropriate Operating System result code. (The warning under
  60950.      ChangedResource above concerning the resChanged attribute also applies
  60951.      to AddResource.)
  60952.  
  60953. Warning:  AddResource doesn’t verify whether the resource ID you pass is
  60954.           already assigned to another resource of the same type; be sure to
  60955.           call UniqueID before adding a resource.
  60956.  
  60957.  
  60958. æKY Retrace.h
  60959. æKL AttachVBL
  60960. DoVBLTask
  60961. GetVBLQHdr
  60962. SlotVInstall
  60963. SlotVRemove
  60964. VInstall
  60965. VRemove
  60966.  
  60967.  
  60968. æKY GetVBLQHdr
  60969. æFc Retrace.h
  60970. æT Function
  60971. æD pascal QHdrPtr GetVBLQHdr(void); 
  60972. æDT QHdrPtr myVariable = GetVBLQHdr()(void);
  60973. æRI II-352
  60974. æC 
  60975. [Not in ROM]
  60976.  
  60977. GetVBLQHdr returns a pointer to the header of the vertical retrace queue.
  60978.  
  60979. Assembly-language note:  The global variable VBLQueue contains the header
  60980.                          of the vertical retrace queue.
  60981.  
  60982. æKY SlotVInstall
  60983. æFc Retrace.h
  60984. æT Function
  60985. æD pascal OSErr SlotVInstall(QElemPtr vblBlockPtr,short theSlot); 
  60986. æDT OSErr myVariable = SlotVInstall((QElemPtr) vblBlockPtr,(short) theSlot);
  60987. æRT 221
  60988. æRI V-567
  60989. æC 
  60990. Trap macro  _SlotVInstall
  60991. On entry    A0:  vblTaskPtr (pointer)
  60992.             D0:  theSlot (word)
  60993. On exit     D0:  result code (word)
  60994.  
  60995. SlotVInstall is identical in function to the VInstall function except that it installs
  60996. the task in the queue for the device specified by theSlot.
  60997.  
  60998. Result codes    noErr         No error
  60999.                 vTypErr       Invalid queue element
  61000.                 slotNumErr    Invalid slot number
  61001.  
  61002. æKY SlotVRemove
  61003. æFc Retrace.h
  61004. æT Function
  61005. æD pascal OSErr SlotVRemove(QElemPtr vblBlockPtr,short theSlot); 
  61006. æDT OSErr myVariable = SlotVRemove((QElemPtr) vblBlockPtr,(short) theSlot);
  61007. æRI V-567
  61008. æC 
  61009. Trap macro  _SlotVRemove
  61010. On entry    A0:  vblTaskPtr (pointer)
  61011.             D0:  theSlot (word)
  61012. On exit     D0:  result code (word)
  61013.  
  61014. SlotVRemove is identical in function to the VRemove function except that it removes
  61015. the task from the queue for the slot specified by theSlot.
  61016.  
  61017. Result codes    noErr         No error
  61018.                 vTypErr       Invalid queue element
  61019.                 slotNumErr    Invalid slot number
  61020.  
  61021. æKY AttachVBL
  61022. æFc Retrace.h
  61023. æT Function
  61024. æD pascal OSErr AttachVBL(short theSlot); 
  61025. æDT OSErr myVariable = AttachVBL((short) theSlot);
  61026. æRI V-567
  61027. æC 
  61028. Trap macro  _AttachVBL
  61029. On entry    D0:  theSlot (word)
  61030. On exit     D0:  result code (word)
  61031.  
  61032. AttachVBL makes theSlot the primary video slot, allowing correct cursor updating.
  61033.  
  61034. Result codes    noErr         No error
  61035.                 slotNumErr    Invalid slot number
  61036.  
  61037. æKY DoVBLTask
  61038. æFc Retrace.h
  61039. æT Function
  61040. æD pascal OSErr DoVBLTask(short theSlot); 
  61041. æDT OSErr myVariable = DoVBLTask((short) theSlot);
  61042. æRI V-568
  61043. æC 
  61044. Trap macro  _DoVBLTask
  61045. On entry    D0:  theSlot (word)
  61046. On exit     D0:  result code (word)
  61047.  
  61048. Note:  To reduce overhead at interrupt time, instead of executing the
  61049.        _DoVBLTask trap you can load the jump vector jDoVBLTask into an
  61050.        address register and execute a JSR instruction using that register.
  61051.  
  61052. DoVBLTask causes any VBL tasks in the queue for the specified slot to be executed. 
  61053. If the specified slot is the primary video slot, the position of the cursor will also
  61054. be updated.
  61055.  
  61056. Result codes    noErr         No error
  61057.                 slotNumErr    Invalid slot number
  61058.  
  61059. æKY VInstall
  61060. æFc Retrace.h
  61061. æT Function
  61062. æD pascal OSErr VInstall(QElemPtr vblTaskPtr); 
  61063. æDT OSErr myVariable = VInstall((QElemPtr) vblTaskPtr);
  61064. æRI II-351
  61065. æC 
  61066. Trap macro  _VInstall
  61067. On entry    A0:  vblTaskPtr (pointer)
  61068. On exit     D0:  result code (word)
  61069.  
  61070. VInstall adds the VBL task specified by vblTaskPtr to the vertical retrace queue.
  61071. Your application must fill in all fields of the task except qLink. VInstall returns
  61072. one of the result codes listed below.
  61073.  
  61074. Result codes    noErr      No error
  61075.                 vTypErr    QType field isn’t ORD(vType)
  61076.  
  61077. æKY VRemove
  61078. æFc Retrace.h
  61079. æT Function
  61080. æD pascal OSErr VRemove(QElemPtr vblTaskPtr); 
  61081. æDT OSErr myVariable = VRemove((QElemPtr) vblTaskPtr);
  61082. æRI II-351
  61083. æC 
  61084. Trap macro  _VRemove
  61085. On entry    A0:  vblTaskPtr (pointer)
  61086. On exit     D0:  result code (word)
  61087.  
  61088. VRemove removes the VBL task specified by vblTaskPtr from the vertical retrace queue.
  61089. It returns one of the result codes listed below.
  61090.  
  61091. Result codes    noErr      No error
  61092.                 vTypErr    QType field isn’t ORD(vType)
  61093.                 qErr       Task entry isn’t in the queue
  61094.  
  61095.  
  61096. æKY ROMDefs.h
  61097. æKL 
  61098. appleFormat
  61099. board
  61100. boardFlags
  61101. boardId
  61102. catBoard
  61103. catDisplay
  61104. catNetwork
  61105. catTest
  61106. date
  61107. defaultTO
  61108. displayVideoAppleGM
  61109. displayVideoAppleTFB
  61110. drHw3Com
  61111. drHwBSC
  61112. drHwTFB
  61113. drSwApple
  61114. endOfList
  61115. majorBaseOS
  61116. majorLength
  61117. minorBaseOS
  61118. minorLength
  61119. networkEtherNetApple3Com
  61120. partNum
  61121. pRAMInitData
  61122. primaryInit
  61123. revLevel
  61124. romRevision
  61125. sCodeRev
  61126. sCPU68000
  61127. sCPU68020
  61128. sCPU68030
  61129. sCPU68040
  61130. sDRVRDir
  61131. serialNum
  61132. sMacOS68000
  61133. sMacOS68020
  61134. sMacOS68030
  61135. sMacOS68040
  61136. sRsrcBootRec
  61137. sRsrcDrvrDir
  61138. sRsrcFlags
  61139. sRsrcHWDevId
  61140. sRsrcIcon
  61141. sRsrcLoadDir
  61142. sRsrcName
  61143. sRsrcType
  61144. testByte
  61145. testLong
  61146. testPattern
  61147. testSimpleAppleAny
  61148. testString
  61149. testWord
  61150. timeOutConst
  61151. typeApple
  61152. typeBoard
  61153. typeEtherNet
  61154. typeVideo
  61155. vendorId
  61156. vendorInfo
  61157.  
  61158. æKY appleFormat
  61159. æFc ROMDefs.h
  61160. æT #define
  61161. æD #define appleFormat 1 /*Format of Declaration Data (IEEE will assign real value)*/
  61162. æC 
  61163.  
  61164. æKY romRevision
  61165. æFc ROMDefs.h
  61166. æT #define
  61167. æD #define romRevision 1 /*Revision of Declaration Data Format*/
  61168. æC 
  61169.  
  61170. æKY testPattern
  61171. æFc ROMDefs.h
  61172. æT #define
  61173. æD #define testPattern 1519594439 /*FHeader long word test pattern*/
  61174. æC 
  61175.  
  61176. æKY sCodeRev
  61177. æFc ROMDefs.h
  61178. æT #define
  61179. æD #define sCodeRev 2 /*Revision of code (For sExec)*/
  61180. æC 
  61181.  
  61182. æKY sCPU68000
  61183. æFc ROMDefs.h
  61184. æT #define
  61185. æD #define sCPU68000 1 /*CPU type = 68000*/
  61186. æC 
  61187.  
  61188. æKY sCPU68020
  61189. æFc ROMDefs.h
  61190. æT #define
  61191. æD #define sCPU68020 2 /*CPU type = 68020*/
  61192. æC 
  61193.  
  61194. æKY sCPU68030
  61195. æFc ROMDefs.h
  61196. æT #define
  61197. æD #define sCPU68030 3 /*CPU type = 68030*/
  61198. æC 
  61199.  
  61200. æKY sCPU68040
  61201. æFc ROMDefs.h
  61202. æT #define
  61203. æD #define sCPU68040 4 /*CPU type = 68040*/
  61204. æC 
  61205.  
  61206. æKY sMacOS68000
  61207. æFc ROMDefs.h
  61208. æT #define
  61209. æD #define sMacOS68000 1 /*Mac OS, CPU type = 68000*/
  61210. æC 
  61211.  
  61212. æKY sMacOS68020
  61213. æFc ROMDefs.h
  61214. æT #define
  61215. æD #define sMacOS68020 2 /*Mac OS, CPU type = 68020*/
  61216. æC 
  61217.  
  61218. æKY sMacOS68030
  61219. æFc ROMDefs.h
  61220. æT #define
  61221. æD #define sMacOS68030 3 /*Mac OS, CPU type = 68030*/
  61222. æC 
  61223.  
  61224. æKY sMacOS68040
  61225. æFc ROMDefs.h
  61226. æT #define
  61227. æD #define sMacOS68040 4 /*Mac OS, CPU type = 68040*/
  61228. æC 
  61229.  
  61230. æKY board
  61231. æFc ROMDefs.h
  61232. æT #define
  61233. æD #define board 0 /*Board sResource - Required on all boards*/
  61234. æC 
  61235.  
  61236. æKY displayVideoAppleTFB
  61237. æFc ROMDefs.h
  61238. æT #define
  61239. æD #define displayVideoAppleTFB 16843009 /*Video with Apple parameters for TFB card.*/
  61240. æC 
  61241.  
  61242. æKY displayVideoAppleGM
  61243. æFc ROMDefs.h
  61244. æT #define
  61245. æD #define displayVideoAppleGM 16843010 /*Video with Apple parameters for GM card.*/
  61246. æC 
  61247.  
  61248. æKY networkEtherNetApple3Com
  61249. æFc ROMDefs.h
  61250. æT #define
  61251. æD #define networkEtherNetApple3Com 33620225 /*Ethernet with apple parameters for 3-Comm card.*/
  61252. æC 
  61253.  
  61254. æKY testSimpleAppleAny
  61255. æFc ROMDefs.h
  61256. æT #define
  61257. æD #define testSimpleAppleAny -2147417856 /*A simple test sResource.*/
  61258. æC #define testSimpleAppleAny   -2147417856 /*A simple test sResource.*/
  61259.  
  61260. æKY endOfList
  61261. æFc ROMDefs.h
  61262. æT #define
  61263. æD #define endOfList 255 /*End of list*/
  61264. æC 
  61265.  
  61266. æKY defaultTO
  61267. æFc ROMDefs.h
  61268. æT #define
  61269. æD #define defaultTO 100 /*100 retries.*/
  61270. æC 
  61271.  
  61272. æKY sRsrcType
  61273. æFc ROMDefs.h
  61274. æT #define
  61275. æD #define sRsrcType 1 /*Type of sResource*/
  61276. æC 
  61277.  
  61278. æKY sRsrcName
  61279. æFc ROMDefs.h
  61280. æT #define
  61281. æD #define sRsrcName 2 /*Name of sResource*/
  61282. æC 
  61283.  
  61284. æKY sRsrcIcon
  61285. æFc ROMDefs.h
  61286. æT #define
  61287. æD #define sRsrcIcon 3 /*Icon*/
  61288. æC 
  61289.  
  61290. æKY sRsrcDrvrDir
  61291. æFc ROMDefs.h
  61292. æT #define
  61293. æD #define sRsrcDrvrDir 4 /*Driver directory*/
  61294. æC 
  61295.  
  61296. æKY sRsrcLoadDir
  61297. æFc ROMDefs.h
  61298. æT #define
  61299. æD #define sRsrcLoadDir 5 /*Load directory*/
  61300. æC 
  61301.  
  61302. æKY sRsrcBootRec
  61303. æFc ROMDefs.h
  61304. æT #define
  61305. æD #define sRsrcBootRec 6 /*sBoot record*/
  61306. æC 
  61307.  
  61308. æKY sRsrcFlags
  61309. æFc ROMDefs.h
  61310. æT #define
  61311. æD #define sRsrcFlags 7 /*sResource Flags*/
  61312. æC 
  61313.  
  61314. æKY sRsrcHWDevId
  61315. æFc ROMDefs.h
  61316. æT #define
  61317. æD #define sRsrcHWDevId 8 /*Hardware Device Id*/
  61318. æC 
  61319.  
  61320. æKY minorBaseOS
  61321. æFc ROMDefs.h
  61322. æT #define
  61323. æD #define minorBaseOS 10 /*Offset to base of sResource in minor space.*/
  61324. æC 
  61325.  
  61326. æKY minorLength
  61327. æFc ROMDefs.h
  61328. æT #define
  61329. æD #define minorLength 11
  61330. æC 
  61331.  
  61332. æKY majorBaseOS
  61333. æFc ROMDefs.h
  61334. æT #define
  61335. æD #define majorBaseOS 12 /*Offset to base of sResource in Major space.*/
  61336. æC 
  61337.  
  61338. æKY majorLength
  61339. æFc ROMDefs.h
  61340. æT #define
  61341. æD #define majorLength 13
  61342. æC 
  61343.  
  61344. æKY sDRVRDir
  61345. æFc ROMDefs.h
  61346. æT #define
  61347. æD #define sDRVRDir 16 /*sDriver directory*/
  61348. æC 
  61349.  
  61350. æKY drSwApple
  61351. æFc ROMDefs.h
  61352. æT #define
  61353. æD #define drSwApple 1
  61354. æC 
  61355.  
  61356. æKY drHwTFB
  61357. æFc ROMDefs.h
  61358. æT #define
  61359. æD #define drHwTFB 1
  61360. æC 
  61361.  
  61362. æKY drHw3Com
  61363. æFc ROMDefs.h
  61364. æT #define
  61365. æD #define drHw3Com 1
  61366. æC 
  61367.  
  61368. æKY drHwBSC
  61369. æFc ROMDefs.h
  61370. æT #define
  61371. æD #define drHwBSC 3
  61372. æC 
  61373.  
  61374. æKY catBoard
  61375. æFc ROMDefs.h
  61376. æT #define
  61377. æD #define catBoard 1
  61378. æC 
  61379.  
  61380. æKY catTest
  61381. æFc ROMDefs.h
  61382. æT #define
  61383. æD #define catTest 2
  61384. æC 
  61385.  
  61386. æKY catDisplay
  61387. æFc ROMDefs.h
  61388. æT #define
  61389. æD #define catDisplay 3
  61390. æC 
  61391.  
  61392. æKY catNetwork
  61393. æFc ROMDefs.h
  61394. æT #define
  61395. æD #define catNetwork 4
  61396. æC 
  61397.  
  61398. æKY boardId
  61399. æFc ROMDefs.h
  61400. æT #define
  61401. æD #define boardId 32 /*Board Id*/
  61402. æC 
  61403.  
  61404. æKY pRAMInitData
  61405. æFc ROMDefs.h
  61406. æT #define
  61407. æD #define pRAMInitData 33 /*sPRAM init data*/
  61408. æC 
  61409.  
  61410. æKY primaryInit
  61411. æFc ROMDefs.h
  61412. æT #define
  61413. æD #define primaryInit 34 /*Primary init record*/
  61414. æC 
  61415.  
  61416. æKY timeOutConst
  61417. æFc ROMDefs.h
  61418. æT #define
  61419. æD #define timeOutConst 35 /*Time out constant*/
  61420. æC 
  61421.  
  61422. æKY vendorInfo
  61423. æFc ROMDefs.h
  61424. æT #define
  61425. æD #define vendorInfo 36 /*Vendor information List. See Vendor List, below*/
  61426. æC 
  61427.  
  61428. æKY boardFlags
  61429. æFc ROMDefs.h
  61430. æT #define
  61431. æD #define boardFlags 37 /*Board Flags*/
  61432. æC 
  61433.  
  61434. æKY vendorId
  61435. æFc ROMDefs.h
  61436. æT #define
  61437. æD #define vendorId 1 /*Vendor Id*/
  61438. æC 
  61439.  
  61440. æKY serialNum
  61441. æFc ROMDefs.h
  61442. æT #define
  61443. æD #define serialNum 2 /*Serial number*/
  61444. æC 
  61445.  
  61446. æKY revLevel
  61447. æFc ROMDefs.h
  61448. æT #define
  61449. æD #define revLevel 3 /*Revision level*/
  61450. æC 
  61451.  
  61452. æKY partNum
  61453. æFc ROMDefs.h
  61454. æT #define
  61455. æD #define partNum 4 /*Part number*/
  61456. æC 
  61457.  
  61458. æKY date
  61459. æFc ROMDefs.h
  61460. æT #define
  61461. æD #define date 5 /*Last revision date of the card*/
  61462. æC 
  61463.  
  61464. æKY typeBoard
  61465. æFc ROMDefs.h
  61466. æT #define
  61467. æD #define typeBoard 0
  61468. æC 
  61469.  
  61470. æKY typeApple
  61471. æFc ROMDefs.h
  61472. æT #define
  61473. æD #define typeApple 1
  61474. æC 
  61475.  
  61476. æKY typeVideo
  61477. æFc ROMDefs.h
  61478. æT #define
  61479. æD #define typeVideo 1
  61480. æC 
  61481.  
  61482. æKY typeEtherNet
  61483. æFc ROMDefs.h
  61484. æT #define
  61485. æD #define typeEtherNet 1
  61486. æC 
  61487.  
  61488. æKY testByte
  61489. æFc ROMDefs.h
  61490. æT #define
  61491. æD #define testByte 32 /*Test byte.*/
  61492. æC #define testByte 32 /*Test byte.*/
  61493.  
  61494. æKY testWord
  61495. æFc ROMDefs.h
  61496. æT #define
  61497. æD #define testWord 33 /*0021*/
  61498. æC 
  61499.  
  61500. æKY testLong
  61501. æFc ROMDefs.h
  61502. æT #define
  61503. æD #define testLong 34 /*Test Long.*/
  61504. æC 
  61505.  
  61506. æKY testString
  61507. æFc ROMDefs.h
  61508. æT #define
  61509. æD #define testString 35 /*Test String.*/
  61510. æC 
  61511.  
  61512.  
  61513. æKY Sane.h
  61514. æKL annuity
  61515. classcomp
  61516. classdouble
  61517. classextended
  61518. classfloat
  61519. compound
  61520. copysign
  61521. dec2num
  61522. dec2str
  61523. exp1
  61524. exp2
  61525. getenvironment
  61526. gethaltvector
  61527. getprecision
  61528. getround
  61529. gettrapvector
  61530. inf
  61531. ipower
  61532. log1
  61533. log2
  61534. logb
  61535. nan
  61536. nextdouble
  61537. nextextended
  61538. nextfloat
  61539. num2dec
  61540. pi
  61541. power
  61542. procentry
  61543. procexit
  61544. randomx
  61545. relation
  61546. remainder
  61547. rint
  61548. scalb
  61549. setenvironment
  61550. setexception
  61551. sethalt
  61552. sethaltvector
  61553. setprecision
  61554. setround
  61555. settrapvector
  61556. signnum
  61557. str2dec
  61558. testexception
  61559. testhalt
  61560. x80tox96
  61561. x96tox80
  61562.  
  61563. CURBSONUNOR
  61564. CURDIVBYZERO
  61565. CURINEX1
  61566. CURINEX2
  61567. CUROPERROR
  61568. CUROVERFLOW
  61569. CURSIGNAN
  61570. CURUNDERFLOW
  61571. DBLPRECISION
  61572. decform
  61573. decimal
  61574. DECSTROUTLEN
  61575. DENORMALNUM
  61576. DIVBYZERO
  61577. DOWNWARD
  61578. environment
  61579. EQUALTO
  61580. exception
  61581. extended80
  61582. extended96
  61583. EXTPRECISION
  61584. FIXEDDECIMAL
  61585. FLOATDECIMAL
  61586. FLOATPRECISION
  61587. GREATERTHAN
  61588. haltvector
  61589. IEEEDEFAULTENV
  61590. INEXACT
  61591. INFINITE
  61592. INVALID
  61593. LESSTHAN
  61594. mischaltinfo
  61595. NORMALNUM
  61596. numclass
  61597. OVERFLOW
  61598. QNAN
  61599. relop
  61600. rounddir
  61601. roundpre
  61602. SIGDIGLEN
  61603. SNAN
  61604. TONEAREST
  61605. TOWARDZERO
  61606. trapvector
  61607. UNDERFLOW
  61608. UNORDERED
  61609. UPWARD
  61610. ZERONUM
  61611.  
  61612. æKY annuity
  61613. æFc SANE.h
  61614. æT Function
  61615. æD extended annuity(extended r,extended n);
  61616. æDT extended myVariable = annuity((extended)r,(extended)n);
  61617. æC Synopsis
  61618.  
  61619. #include <SANE.h>
  61620. extended annuity(extended r,extended n);
  61621.  
  61622.                           Description
  61623.  
  61624. The annuity function computes
  61625.  
  61626.         annuity(r,n) = (1 - (1 + r)^(-n)) / r   when r <> 0,
  61627.  
  61628. where r is the interest rate and n is the number of periods.
  61629. Annuity is more accurate than the straightforward computation
  61630. of the expression above using basic arithmetic operations and
  61631. exponentiation.  The annuity function is directly applicable to
  61632. the computation of present and future values of ordinary annuities:
  61633.  
  61634.         PV = PMT * (1 - (1 + r)^(-n)) / r
  61635.                = PMT * annuity(r,n)
  61636.  
  61637.         FV = PMT * ((1 + r)^n - 1) / r
  61638.              = PMT * (1 + r)^n * (1 - (1 + r)^(-n)) / r
  61639.              = PMT * compound(r,n) * annuity(r,n)
  61640.  
  61641. where PMT is the amount of one periodic payment.
  61642.  
  61643. Special cases for annuity:
  61644.  
  61645. If r = 0, then annuity(r,n) computes the sum of 1 + 1 + ... + 1
  61646. over n periods, and therefore returns the value n and signals no 
  61647. exceptions (the value n corresponds to the limit as r approaches 0).
  61648.  
  61649. If r < –1, then annuity(r,n) returns a quiet NaN and signals invalid,
  61650. because the function is intended for financial contexts where
  61651. r < –1 is regarded as a mistake.
  61652.  
  61653. If r = –1 and n > 0, then annuity(r,n) returns +INF and signals
  61654. divide-by-zero.
  61655.  
  61656.                           Diagnostics
  61657.  
  61658. The annuity function honors the floating-point exception flags——
  61659. invalid operation, underflow, overflow, divide-by-zero, and
  61660. inexact——as prescribed by SANE.
  61661.  
  61662. See also
  61663. compound
  61664. Apple Numerics Manual, 2nd edition
  61665.  
  61666.  
  61667. æKY classcomp
  61668. æFc SANE.h
  61669. æT Function
  61670. æD numclass classcomp(extended x);
  61671. æDT numclass myVariable = classcomp((extended)x);
  61672. æC Synopsis
  61673.  
  61674. #include <SANE.h>
  61675. numclass classcomp(extended x);
  61676.  
  61677.                           Description
  61678.  
  61679. The classcomp function returns the number class of its extended 
  61680. argument as if that argument were of type comp.  The argument is
  61681. converted to type comp and then back to extended format.  It is
  61682. then classified via the classextended function.
  61683.  
  61684.                           Diagnostics
  61685.  
  61686. Although classify operations as a rule do not raise floating-point
  61687. exception flags, the classcomp function may raise the invalid
  61688. operation exception or inexact exception during the extended-to-comp
  61689. conversion phase of the classification.
  61690.  
  61691. See also
  61692. numclass, classdouble, classextended, classfloat
  61693. Apple Numerics Manual, 2nd edition
  61694.  
  61695.  
  61696. æKY classdouble
  61697. æFc SANE.h
  61698. æT Function
  61699. æD numclass classdouble(extended x);
  61700. æDT numclass myVariable = classdouble((extended)x);
  61701. æC Synopsis
  61702.  
  61703. #include <SANE.h>
  61704. numclass classdouble(extended x);
  61705.  
  61706.                           Description
  61707.  
  61708. The classdouble function returns the number class of its extended 
  61709. argument as if that argument were of type double.  The argument is
  61710. converted to type double and then classified by the FCLASSD SANE
  61711. operation.
  61712.  
  61713.                           Diagnostics
  61714.  
  61715. Although classify operations as a rule do not raise floating-point
  61716. exception flags, the classdouble function may raise the invalid
  61717. operation, underflow, overflow, or inexact exceptions during the
  61718. extended-to-double conversion phase of the classification.
  61719.  
  61720. See also
  61721. numclass, classcomp, classextended, classfloat
  61722. Apple Numerics Manual, 2nd edition
  61723.  
  61724.  
  61725. æKY classextended
  61726. æFc SANE.h
  61727. æT Function
  61728. æD numclass classextended(extended x);
  61729. æDT numclass myVariable = classextended((extended)x);
  61730. æC Synopsis
  61731.  
  61732. #include <SANE.h>
  61733. numclass classextended(extended x);
  61734.  
  61735.                           Description
  61736.  
  61737. The classextended function returns the number class of its extended 
  61738. argument.  The argument undergoes an extended-to-extended conversion
  61739. and is then classified by the FCLASSX SANE operation.
  61740.  
  61741.                           Diagnostics
  61742.  
  61743. The classextended function does not raise any floating-point
  61744. exception flags.
  61745.  
  61746. See also
  61747. numclass, classcomp, classdouble, classfloat
  61748. Apple Numerics Manual, 2nd edition
  61749.  
  61750.  
  61751. æKY classfloat
  61752. æFc SANE.h
  61753. æT Function
  61754. æD numclass classfloat(extended x);
  61755. æDT numclass myVariable = classfloat((extended)x);
  61756. æC Synopsis
  61757.  
  61758. #include <SANE.h>
  61759. numclass classfloat(extended x);
  61760.  
  61761.                           Description
  61762.  
  61763. The classfloat function returns the number class of its extended 
  61764. argument as if that argument were of type float.  The argument is
  61765. converted to type float and then classified by the FCLASSS SANE
  61766. operation.
  61767.  
  61768.                           Diagnostics
  61769.  
  61770. Although classify operations as a rule do not raise floating-point
  61771. exception flags, the classfloat function may raise the invalid
  61772. operation, underflow, overflow, or inexact exceptions during the
  61773. extended-to-float conversion phase of the classification.
  61774.  
  61775. See also
  61776. numclass, classcomp, classdouble, classextended
  61777. Apple Numerics Manual, 2nd edition
  61778.  
  61779.  
  61780. æKY compound
  61781. æFc SANE.h
  61782. æT Function
  61783. æD extended compound(extended r,extended n);
  61784. æDT extended myVariable = compound((extended)r,(extended)n);
  61785. æC Synopsis
  61786.  
  61787. #include <SANE.h>
  61788. extended compound(extended r,extended n); 
  61789.  
  61790.                           Description
  61791.  
  61792. The compound function computes
  61793.  
  61794.         compound(r,n) = (1 + r)^n,
  61795.  
  61796. where r is the interest rate and n is the number (perhaps
  61797. nonintegral) of periods.  When the rate r is small, compound
  61798. gives a more accurate computation than does the straightforward
  61799. computation of (1 + r)^n by addition and exponentiation.
  61800.  
  61801. The compound function is directly applicable to computation of 
  61802. present and future values:  
  61803.  
  61804.         PV = FV * (1 + r)^(-n) = FV / compound(r,n)
  61805.         FV = PV * (1 + r)^n = PV * compound(r,n)
  61806.  
  61807. Special cases for compound:
  61808.  
  61809. If r = 0 and n is infinite, or if r < –1, then compound(r,n)
  61810. returns a quiet NaN and signals invalid. (The compound function
  61811. is intended for financial contexts where r < –1 is regarded as
  61812. a mistake.)
  61813.  
  61814. If r = –1 and n < 0, then compound(r,n) returns +INF and signals
  61815. divide-by-zero.
  61816.  
  61817.                           Diagnostics
  61818.  
  61819. The compound function honors the floating-point exception flags——
  61820. invalid operation, underflow, overflow, divide-by-zero, and
  61821. inexact——as prescribed by SANE.
  61822.  
  61823. See also
  61824. annuity
  61825. Apple Numerics Manual, 2nd edition
  61826.  
  61827.  
  61828. æKY copysign
  61829. æFc SANE.h
  61830. æT Function
  61831. æD extended copysign(extended x,extended y);
  61832. æDT extended myVariable = copysign((extended)x,(extended)y);
  61833. æC Synopsis
  61834.  
  61835. #include <SANE.h>
  61836. extended copysign(extended x,extended y);
  61837.  
  61838.                           Description
  61839.  
  61840. The copysign(x,y) function returns the magnitude of y with the sign
  61841. of x.
  61842.  
  61843. In non-mc68881 mode, copysign is considered a non-arithmetic
  61844. operation.  As such, it raises none of the floating-point exception
  61845. flags.
  61846.  
  61847. In mc68881 mode, if y is a signaling NaN, copysign(x,y) raises
  61848. the invalid and CURSIGNAN exception flags and returns a quiet
  61849. NaN with the sign of x.
  61850.  
  61851.                           Diagnostics
  61852.  
  61853. The copysign function honors the invalid operation exception, as
  61854. specified by SANE, in mc68881 mode only.
  61855.  
  61856. See also
  61857. Apple Numerics Manual, 2nd edition
  61858.  
  61859.  
  61860. æKY dec2num
  61861. æFc SANE.h
  61862. æT Function
  61863. æD extended dec2num(const decimal *d);
  61864. æDT extended myVariable = dec2num((const decimal *)d);
  61865. æC Synopsis
  61866.  
  61867. #include <SANE.h>
  61868. extended dec2num(const decimal *d);
  61869.  
  61870.                           Description
  61871.  
  61872. The dec2num function converts a structure of type decimal to its
  61873. nearest extended floating-point equivalent.
  61874.  
  61875. For certain character string patterns in the decimal structure *d,
  61876. dec2num(d) returns a signed infinity or a quiet NaN.
  61877.  
  61878.                           Diagnostics
  61879.  
  61880. The dec2num function honors three floating-point point exception
  61881. flags——underflow, overflow, and inexact——as prescribed by SANE.
  61882.  
  61883. See also
  61884. decimal, num2dec
  61885. Apple Numerics Manual, 2nd edition
  61886.  
  61887.  
  61888. æKY dec2str
  61889. æFc SANE.h
  61890. æT Function
  61891. æTN 0xA9EE
  61892. æD void dec2str(const decform *f,const decimal *d,char *s);
  61893. æDT dec2str((const decform *)f,(const decimal *)d,(char *)s);   
  61894. æC Synopsis
  61895.  
  61896. #include <SANE.h>
  61897. void dec2str(const decform *f,const decimal *d,char *s);
  61898.  
  61899.                           Description
  61900.  
  61901. The formatting routine dec2str(f,d,s) formats the decimal structure
  61902. *d according to the decform structure *f and writes the result to
  61903. the character array *s.  The maximum length of the result is
  61904. DECSTROUTLEN characters.
  61905.  
  61906.                           Diagnostics
  61907.  
  61908. The dec2str formatter raises no floating-point exception flags.
  61909.  
  61910. See also
  61911. decform, decimal, DECSTROUTLEN, str2dec
  61912. Apple Numerics Manual, 2nd edition
  61913.  
  61914.  
  61915. æKY exp1
  61916. æFc SANE.h
  61917. æT Function
  61918. æD extended exp1(extended x);
  61919. æDT extended myVariable = exp1((extended)x);
  61920. æC Synopsis
  61921.  
  61922. #include <SANE.h>
  61923. extended exp1(extended x); 
  61924.  
  61925.                           Description
  61926.  
  61927. The function exp1(x) accurately computes e^x – 1. If the input
  61928. argument x is small, then the computation of exp1(x) is more
  61929. accurate than the straightforward computation of exp(x) – 1.
  61930.  
  61931. Special cases for exp1:
  61932.  
  61933. If x = +INF, then exp1(x) returns +INF and does not signal an
  61934.   exception.
  61935. If x = –INF, then exp1(x) returns -1 and does not signal an
  61936.   exception.
  61937. If x is a NaN, then exp1(x) returns a quiet NaN.
  61938.  
  61939. --------------------
  61940. EXAMPLE: using exp1
  61941.  
  61942. Financial applications often compute a value r for internal rate
  61943. of return given the compounded value q defined as
  61944.  
  61945.         q(r,n) = (1 + r)^n
  61946.  
  61947. For very large values of n, the following obvious expression for r
  61948. gives errors:
  61949.  
  61950.         r = exp(log(q) * (1/n)) -1
  61951.  
  61952. A better expression for large n uses exp1, like this:
  61953.  
  61954.         r = exp1(log(q) * (1/n))
  61955. --------------------
  61956.  
  61957.                           Diagnostics
  61958.                           
  61959. The function exp1(x) honors the four floating-point exception
  61960. flags——invalid operation, underflow, overflow, and inexact——as
  61961. prescribed by SANE.
  61962.  
  61963. See also
  61964. exp, exp2
  61965. Apple Numerics Manual, 2nd edition
  61966.  
  61967.  
  61968. æKY exp2
  61969. æFc SANE.h
  61970. æT Function
  61971. æD extended exp2(extended x);
  61972. æDT extended myVariable = exp2((extended)x);
  61973. æC Synopsis
  61974.  
  61975. #include <SANE.h>
  61976. extended exp2(extended x); 
  61977.  
  61978.                           Description
  61979.  
  61980. The function exp(x) returns the base-2 exponential 2^x.
  61981.  
  61982. Special cases for exp2:
  61983.  
  61984. If x = +INF, then exp2(x) returns +INF and does not signal an
  61985.   exception. 
  61986. If x = –INF, then exp2(x) returns 0 and does not signal an
  61987.   exception.
  61988. If x is a NaN, then exp2(x) returns a quiet NaN.
  61989.  
  61990.                           Diagnostics
  61991.                           
  61992. The function exp2(x) honors the four floating-point exception
  61993. flags——invalid operation, underflow, overflow, and inexact——as
  61994. prescribed by SANE.
  61995.  
  61996. See also
  61997. exp, exp1
  61998. Apple Numerics Manual, 2nd edition
  61999.  
  62000.  
  62001. æKY getenvironment
  62002. æFc SANE.h
  62003. æT Function
  62004. æD void getenvironment(environment *e);
  62005. æDT getenvironment((environment *)e);
  62006. æC Synopsis
  62007.  
  62008. #include <SANE.h>
  62009. void getenvironment(environment *e);
  62010.  
  62011.                           Description
  62012.  
  62013. The function getenvironment(e) with environment pointer argument e
  62014. sets *e to the current floating-point environment.  This function
  62015. allows the user to read all settings of the floating-point
  62016. environment:  rounding direction, rounding precision, exception
  62017. flags, and halts/traps which are enabled.
  62018.  
  62019.                           Diagnostics
  62020.  
  62021. The getenvironment function raises no floating-point exception flags.
  62022.  
  62023. See also
  62024. environment, setenvironment, procentry, procexit
  62025. Apple Numerics Manual, 2nd edition
  62026.  
  62027.  
  62028. æKY gethaltvector
  62029. æFc SANE.h
  62030. æT Function
  62031. æD #ifndef mc68881
  62032. haltvector gethaltvector(void);
  62033. #endif
  62034. æDT haltvector myVariable = gethaltvector();
  62035. æC Synopsis
  62036.  
  62037. #include <SANE.h>
  62038. #ifndef mc68881
  62039. haltvector gethaltvector(void);
  62040. #endif
  62041.  
  62042.                           Description
  62043.  
  62044. The function gethaltvector() returns the current value of the
  62045. haltvector, or pointer to the halt handling routine.  The haltvector
  62046. is only defined if the mc68881 compiler option is not selected.
  62047.  
  62048.                           Diagnostics
  62049.  
  62050. The gethaltvector function raises no floating-point exception flags.
  62051.  
  62052. See also
  62053. haltvector, sethaltvector
  62054. Apple Numerics Manual, 2nd edition
  62055.  
  62056.  
  62057. æKY getprecision
  62058. æFc SANE.h
  62059. æT Function
  62060. æD roundpre getprecision(void);
  62061. æDT roundpre myVariable = getprecision();
  62062. æC Synopsis
  62063.  
  62064. #include <SANE.h>
  62065. roundpre getprecision(void);
  62066.  
  62067.                           Description
  62068.  
  62069. The function getprecision() returns the current value of the
  62070. floating-point rounding precision.
  62071.  
  62072.                           Diagnostics
  62073.  
  62074. The getprecision function raises no floating-point exception flags.
  62075.  
  62076. See also
  62077. roundpre, setprecision, getenvironment
  62078. Apple Numerics Manual, 2nd edition
  62079.  
  62080.  
  62081. æKY getround
  62082. æFc SANE.h
  62083. æT Function
  62084. æD rounddir getround(void);
  62085. æDT rounddir myVariable = getround();
  62086. æC Synopsis
  62087.  
  62088. #include <SANE.h>
  62089. rounddir getround(void);
  62090.  
  62091.                           Description
  62092.  
  62093. The function getround() returns the current value of the floating-
  62094. point rounding direction.
  62095.                           Diagnostics
  62096.  
  62097. The getround function raises no floating-point exception flags.
  62098.  
  62099. See also
  62100. rounddir, setround
  62101. Apple Numerics Manual, 2nd edition
  62102.  
  62103.  
  62104. æKY gettrapvector
  62105. æFc SANE.h
  62106. æT Function
  62107. æD #ifdef mc68881
  62108. struct trapvector gettrapvector(void);
  62109. #endif
  62110. æDT struct trapvector myVariable = gettrapvector();
  62111. æC Synopsis
  62112.  
  62113. #include <SANE.h>
  62114. #ifdef mc68881
  62115. struct trapvector gettrapvector(void);
  62116. #endif
  62117.  
  62118.                           Description
  62119.  
  62120. The function gettrapvector() returns the current trapvector
  62121. structure for the MC68881 math coprocessor.  The trapvector is
  62122. only defined if the mc68881 compiler option is selected.
  62123.  
  62124.                           Diagnostics
  62125.  
  62126. The gettrapvector function raises no floating-point exception flags.
  62127.  
  62128. See also
  62129. trapvector, settrapvector
  62130. Apple Numerics Manual, 2nd edition
  62131. MC68881/MC68882 Floating-Point Coprocessor User's Manual
  62132.  
  62133.  
  62134. æKY inf
  62135. æFc SANE.h
  62136. æT Function
  62137. æD extended inf(void);
  62138. æDT extended myVariable = inf();
  62139. æC Synopsis
  62140.  
  62141. #include <SANE.h>
  62142. extended inf(void);
  62143.  
  62144.                           Description
  62145.  
  62146. The extended function inf() returns positive infinity.  Infinity
  62147. is a special value which represents a mathematical infinity or any
  62148. number greater in magnitude than the largest finite representable
  62149. number in a given floating-point format.  Infinities are signed.
  62150.  
  62151.                           Diagnostics
  62152.  
  62153. The function inf() raises no floating-point exception flags.
  62154.  
  62155. See also
  62156. HUGE_VAL
  62157. Apple Numerics Manual, 2nd edition
  62158.  
  62159.  
  62160. æKY ipower
  62161. æFc SANE.h
  62162. æT Function
  62163. æD extended ipower(extended x,short i);
  62164. æDT extended myVariable = ipower((extended)x,(short)i);
  62165. æC Synopsis
  62166.  
  62167. #include <SANE.h>
  62168. extended ipower(extended x,short i); 
  62169.  
  62170.                           Description
  62171.  
  62172. The function ipower(x,i) returns the integer exponential x^i.
  62173.  
  62174. Special cases for ipower:
  62175.  
  62176. If i is 0 and x is not a NaN, then ipower(x,i) returns 1, even
  62177.   if x is 0 or infinite.
  62178. If x is +0 and i is negative, then ipower(x,i) returns +INF
  62179.   and signals divide-by-zero.  
  62180. If x is –0 and i is negative, then ipower(x,i) returns +INF
  62181.   if i is even, or –INF if i is odd.  The function signals
  62182.   divide-by-zero in either case.
  62183.  
  62184.                           Diagnostics
  62185.  
  62186. The function ipower honors the floating-point exception flags——
  62187. invalid operation, underflow, overflow, divide-by-zero, and
  62188. inexact——as prescribed by SANE.
  62189.  
  62190. See also
  62191. power
  62192. Apple Numerics Manual, 2nd edition
  62193.  
  62194.  
  62195. æKY log1
  62196. æFc SANE.h
  62197. æT Function
  62198. æD extended log1(extended x);
  62199. æDT extended myVariable = log1((extended)x);
  62200. æC Synopsis
  62201.  
  62202. #include <SANE.h>
  62203. extended log1(extended x);
  62204.  
  62205.                           Description
  62206.  
  62207. The function log1(x) returns the base e or natural logarithm
  62208. of 1 + x.  For small x, log1(x) is more accurate than log(1+x).
  62209.  
  62210. Special cases for log1:
  62211.  
  62212. If x is +INF, then log1(x) returns +INF and signals no exceptions.
  62213. If x is -1, then log1(x) returns -INF and signals divide-by-zero.  
  62214. If x < -1, then log1(x) returns a quiet NaN and signals invalid.
  62215.  
  62216.                           Diagnostics
  62217.  
  62218. The log1 function honors four floating-point exception flags——
  62219. invalid operation, underflow, divide-by-zero, and inexact——as
  62220. prescribed by SANE.
  62221.  
  62222. See also
  62223. log, log2, logb
  62224. Apple Numerics Manual, 2nd edition
  62225.  
  62226.  
  62227. æKY log2
  62228. æFc SANE.h
  62229. æT Function
  62230. æD extended log2(extended x);
  62231. æDT extended myVariable = log2((extended)x);
  62232. æC Synopsis
  62233.  
  62234. #include <SANE.h>
  62235. extended log2(extended x);
  62236.  
  62237.                           Description
  62238.  
  62239. The function log2(x) returns the base 2 logarithm of its
  62240. argument x.
  62241.  
  62242. Special cases for log2:
  62243.  
  62244. If x is +INF, then log2(x) returns +INF and signals no exceptions.
  62245. If x is 0, then log2(x) returns -INF and signals divide-by-zero.  
  62246. If x < 0, then log2(x) returns a quiet NaN and signals invalid.
  62247.  
  62248.                           Diagnostics
  62249.  
  62250. The log2 function honors three floating-point exception flags——
  62251. invalid operation, divide-by-zero, and inexact——as prescribed
  62252. by SANE.
  62253.  
  62254. See also
  62255. log, log1, logb
  62256. Apple Numerics Manual, 2nd edition
  62257.  
  62258.  
  62259. æKY logb
  62260. æFc SANE.h
  62261. æT Function
  62262. æD extended logb(extended x);
  62263. æDT extended myVariable = logb((extended)x);
  62264. æC Synopsis
  62265.  
  62266. #include <SANE.h>
  62267. extended logb(extended x);
  62268.  
  62269.                           Description
  62270.  
  62271. The function logb(x) returns the binary exponent of its argument
  62272. x as a signed integral value.
  62273.  
  62274. Special cases for logb:
  62275.  
  62276. If x is a subnormal number, the exponent is determined as if x 
  62277.   had first been normalized.
  62278. If x is +/-INF, then logb(x) returns +INF and signals no exceptions.
  62279. If x is 0, then logb(x) returns -INF and signals divide-by-zero.
  62280. If x is a NaN, then logb(x) returns a quiet NaN; only signaling NaN
  62281.   inputs raise the invalid exception flag.  
  62282.  
  62283.                           Diagnostics
  62284.  
  62285. The logb function honors two floating-point exception flags——
  62286. invalid operation and divide-by-zero——as prescribed by SANE.
  62287.  
  62288. See also
  62289. frexp, log, log1, log2, scalb
  62290. Apple Numerics Manual, 2nd edition
  62291.  
  62292.  
  62293. æKY nan
  62294. æFc SANE.h
  62295. æT Function
  62296. æD extended nan(unsigned char c);
  62297. æDT extended myVariable = nan((unsigned char)c);
  62298. æC Synopsis
  62299.  
  62300. #include <SANE.h>
  62301. extended nan(unsigned char c);
  62302.  
  62303.                           Description
  62304.  
  62305. The extended function nan(c) returns a quiet NaN with unsigned
  62306. character code c occupying the second most significant byte of
  62307. the significand.
  62308.  
  62309.                           Diagnostics
  62310.  
  62311. The function nan(c) raises no floating-point exception flags.
  62312.  
  62313. See also
  62314. Apple Numerics Manual, 2nd edition
  62315.  
  62316.  
  62317. æKY nextdouble
  62318. æFc SANE.h
  62319. æT Function
  62320. æD extended nextdouble(extended x,extended y);
  62321. æDT extended myVariable = nextdouble((extended)x,(extended)y);
  62322. æC Synopsis
  62323.  
  62324. #include <SANE.h>
  62325. extended nextdouble(extended x,extended y);
  62326.  
  62327.                           Description
  62328.  
  62329. The function nextdouble(x,y) returns the extended representation
  62330. of the next double value after (double) x in the direction of
  62331. (double) y.  This function is implemented by casting x and y to
  62332. type double, calling a SANE ROM routine which returns a result of
  62333. type double, and casting that result to extended.  The casting of
  62334. x and y to the narrower precision may raise the overflow, underflow,
  62335. invalid, or inexact flags if either x or y is a signaling NaN or
  62336. can not be exactly represented in the narrower precision. 
  62337.  
  62338. Special cases for nextdouble:
  62339.  
  62340. If (double) x = (double) y, then nextdouble(x,y) returns (double) x
  62341.   and signals no exceptions other than those due to the casts.
  62342. If either x or y is a NaN, then nextdouble(x,y) returns a quiet NaN
  62343.   and signals no exceptions other than those due to the casts.
  62344. If (double) x is finite but nextdouble(x,y) is infinite, then
  62345.   overflow and inexact are signaled in addition to exceptions
  62346.   arising from the casts.
  62347. If (double) x != (double) y but (double) nextdouble(x,y) is subnormal
  62348.   or zero, then underflow and inexact are signaled in addition to
  62349.   exceptions arising from the casts.
  62350.  
  62351.                           Diagnostics
  62352.  
  62353. The nextdouble function honors four floating-point exception flags——
  62354. invalid operation, underflow, overflow, and inexact——as prescribed
  62355. by SANE.
  62356.  
  62357. See also
  62358. nextextended,nextfloat
  62359. Apple Numerics Manual, 2nd edition
  62360.  
  62361.  
  62362. æKY nextextended
  62363. æFc SANE.h
  62364. æT Function
  62365. æD extended nextextended(extended x,extended y);
  62366. æDT extended myVariable = nextextended((extended)x,(extended)y);
  62367. æC Synopsis
  62368.  
  62369. #include <SANE.h>
  62370. extended nextextended(extended x,extended y);
  62371.  
  62372.                           Description
  62373.  
  62374. The function nextextended(x,y) returns the next extended value
  62375. after x in the direction of y.
  62376.  
  62377. Special cases for nextextended:
  62378.  
  62379. If x = y, then nextextended(x,y) returns x and signals no exceptions.
  62380. If either x or y is a NaN, then nextextended(x,y) returns a quiet.
  62381.   NaN and signals no exceptions unless either x or y is a signaling
  62382.   NaN, in which case the invalid exception is signaled.
  62383. If x is finite but nextextended(x,y) is infinite, then overflow
  62384.   and inexact are signaled.
  62385. If x != y but nextextended(x,y) is subnormal or zero, then underflow
  62386.   and inexact are signaled.
  62387.  
  62388.                           Diagnostics
  62389.  
  62390. The nextextended function honors four floating-point exception
  62391. flags——invalid operation, underflow, overflow, and inexact——as
  62392. prescribed by SANE.
  62393.  
  62394. See also
  62395. nextdouble,nextfloat
  62396. Apple Numerics Manual, 2nd edition
  62397.  
  62398.  
  62399. æKY nextfloat
  62400. æFc SANE.h
  62401. æT Function
  62402. æD extended nextfloat(extended x,extended y);
  62403. æDT extended myVariable = nextfloat((extended)x,(extended)y);
  62404. æC Synopsis
  62405.  
  62406. #include <SANE.h>
  62407. extended nextfloat(extended x,extended y);
  62408.  
  62409.                           Description
  62410.  
  62411. The function nextfloat(x,y) returns the extended representation
  62412. of the next float value after (float) x in the direction of
  62413. (float) y.  This function is implemented by casting x and y to
  62414. type float, calling a SANE ROM routine which returns a result of
  62415. type float, and casting that result to extended.  The casting of
  62416. x and y to the narrower precision may raise the overflow, underflow,
  62417. invalid, or inexact flags if either x or y is a signaling NaN or
  62418. can not be exactly represented in the narrower precision. 
  62419.  
  62420. Special cases for nextfloat:
  62421.  
  62422. If (float) x = (float) y, then nextfloat(x,y) returns (float) x
  62423.   and signals no exceptions other than those due to the casts.
  62424. If either x or y is a NaN, then nextfloat(x,y) returns a quiet NaN
  62425.   and signals no exceptions other than those due to the casts.
  62426. If (float) x is finite but nextfloat(x,y) is infinite, then overflow
  62427.   and inexact are signaled in addition to exceptions arising from
  62428.   the casts.
  62429. If (float) x != (float) y and (float) nextfloat(x,y) is subnormal
  62430.   or zero, then underflow and inexact are signaled in addition to
  62431.   exceptions arising from the casts.
  62432.  
  62433.                           Diagnostics
  62434.  
  62435. The nextfloat function honors four floating-point exception flags——
  62436. invalid operation, underflow, overflow, and inexact——as prescribed
  62437. by SANE.
  62438.  
  62439. See also
  62440. nextdouble, nextextended
  62441. Apple Numerics Manual, 2nd edition
  62442.  
  62443.  
  62444. æKY num2dec
  62445. æFc SANE.h
  62446. æT Function
  62447. æD void num2dec(const decform *f,extended x,decimal *d);
  62448. æDT num2dec((const decform *)f,(extended)x,(decimal *)d);
  62449. æC Synopsis
  62450.  
  62451. #include <SANE.h>
  62452. void num2dec(const decform *f,extended x,decimal *d);
  62453.  
  62454.                           Description
  62455.  
  62456. The function num2dec(f,x,d) converts the extended number x to the
  62457. decimal structure *d in accordance with the decform structure *f.
  62458. The implementation allows up to SIGDIGLEN decimal digits to be
  62459. entered into the sig field of the decimal structure *d.  The
  62460. implied decimal point is at the right end of the sig field, with
  62461. the exponent (exp) field of *d set accordingly.
  62462.  
  62463. Zeros, infinities, and NaNs are converted to decimal structures
  62464. with special string patterns in their sig fields.  In these cases,
  62465. the exponent fields of the resulting decimal structures are
  62466. undefined.
  62467.  
  62468. Undefined results occur when the number of digits specified in the
  62469. decform structure *f exceed SIGDIGLEN.
  62470.  
  62471. A number may be too large to represent in a given fixed format
  62472. style.  In this case, the string pattern '?' is put into the sig
  62473. field of the decimal structure result.
  62474.  
  62475. Fixed-point formatting treats a negative number in the digits field
  62476. of the decform structure *f as a specification for rounding to the
  62477. left of the decimal point.  For floating-point formatting, a negative
  62478. value for digits yields undefined results.
  62479.  
  62480.                           Diagnostics
  62481.  
  62482. The num2dec function honors two floating-point point exception
  62483. flags——invalid operation and inexact——as prescribed by SANE.
  62484.  
  62485. See also
  62486. dec2num, decform, decimal, SIGDIGLEN
  62487. Apple Numerics Manual, 2nd edition
  62488.  
  62489.  
  62490. æKY pi
  62491. æFc SANE.h
  62492. æT Function
  62493. æD extended pi(void);
  62494. æDT extended myVariable = pi();
  62495. æC Synopsis
  62496.  
  62497. #include <SANE.h>
  62498. extended pi(void);
  62499.  
  62500.                           Description
  62501.  
  62502. The function pi() returns the nearest extended approximation of π.
  62503. The functions cos, sin, and tan are periodic with respect to this
  62504. approximate value of π, so their periods are slightly different
  62505. from their mathematical counterparts.
  62506.  
  62507.                           Diagnostics
  62508.  
  62509. The function pi() raises no floating-point exception flags.
  62510.  
  62511. See also
  62512. cos, sin, tan
  62513. Apple Numerics Manual, 2nd edition
  62514.  
  62515.  
  62516. æKY power
  62517. æFc SANE.h
  62518. æT Function
  62519. æD extended power(extended x, extended y);
  62520. æDT extended myVariable = power((extended)x,(extended)y);
  62521. æC                Synopsis
  62522.  
  62523. #include <SANE.h>
  62524. extended power(extended x, extended y);
  62525.  
  62526.                            Description
  62527.  
  62528. The extended function power(x,y) returns x^y.  It is equivalent to
  62529. the function pow(x,y) declared in Math.h.
  62530.  
  62531. Special cases for power(x,y):
  62532.  
  62533. If x is +0 and y is negative, then power(x,y) returns +INF and
  62534.   signals divide-by-zero.
  62535. If x is -0 and y is integral and negative, then power(x,y) returns
  62536.   +INF if y is even and -INF if y is odd.  Divide-by-zero is
  62537.   signaled in either case.
  62538. If any of the following is true, power(x,y) returns a quiet NaN
  62539.   and signals invalid:  both x and y equal 0; x is infinite and
  62540.   y equals 0; x equals 1 and y is infinite; x is -0 or negative
  62541.   and y is not integral; or either x or y is a signaling NaN.
  62542.  
  62543.                           Diagnostics
  62544.  
  62545. This function honors the floating-point exception flags——
  62546. invalid operation, underflow, overflow, divide by zero, and
  62547. inexact——as prescribed by SANE.
  62548.  
  62549. See also
  62550. pow
  62551. Apple Numerics Manual, 2nd edition
  62552.  
  62553.  
  62554. æKY procentry
  62555. æFc SANE.h
  62556. æT Function
  62557. æD void procentry(environment *e);
  62558. æDT procentry((environment *)e);
  62559. æC                Synopsis
  62560.  
  62561. #include <SANE.h>
  62562. void procentry(environment *e);
  62563.  
  62564.                            Description
  62565.  
  62566. The function procentry(e) saves the current SANE environment in
  62567. environment variable *e and sets the environment to IEEEDEFAULTENV,
  62568. the default IEEE environment.  When used in conjunction with the
  62569. procexit routine, procentry facilitates writing functions that
  62570. appear to their callers to be atomic.
  62571.  
  62572.                           Diagnostics
  62573.  
  62574. By setting the default environment, procentry clears all exception
  62575. flags and halt enables.
  62576.  
  62577. See also
  62578. environment, IEEEDEFAULTENV, procexit
  62579. Apple Numerics Manual, 2nd edition
  62580.  
  62581.  
  62582. æKY procexit
  62583. æFc SANE.h
  62584. æT Function
  62585. æD void procexit(environment e);
  62586. æDT procexit((environment)e);
  62587. æC                Synopsis
  62588.  
  62589. #include <SANE.h>
  62590. void procexit(environment e);
  62591.  
  62592.                            Description
  62593.  
  62594. The function procexit(e) saves the current exception flags in
  62595. temporary storage, sets the environment to e, then signals the
  62596. temporarily saved exceptions.  SANE halts or traps, if enabled
  62597. in e, will occur if their corresponding exceptions are signaled
  62598. by the procexit routine.
  62599.  
  62600. When used in conjunction with the procentry routine, procexit
  62601. facilitates writing functions that appear to their callers to be
  62602. atomic.  Exceptions signaled between procentry and procexit calls
  62603. are hidden from the caller unless they remain raised when procexit
  62604. is called.  Spurious (irrelevant or misleading) exceptions arising
  62605. during the course of a computation may thus be hidden by careful
  62606. programming.
  62607.  
  62608. In mc68881 mode, if any accrued exception bits are set in the
  62609. environment argument e, they are mapped into the appropriate current
  62610. exception bit(s).
  62611.  
  62612.                           Diagnostics
  62613.  
  62614. All floating-point exception flags——invalid operation, underflow,
  62615. overflow, divide-by-zero, and inexact——are honored by procexit.
  62616.  
  62617. See also
  62618. environment, procentry
  62619. Apple Numerics Manual, 2nd edition
  62620.  
  62621.  
  62622. æKY randomx
  62623. æFc SANE.h
  62624. æT Function
  62625. æD extended randomx(extended *x);
  62626. æDT extended myVariable = randomx((extended *)x);
  62627. æC Synopsis
  62628.  
  62629. #include <SANE.h>
  62630. extended randomx(extended *x); 
  62631.  
  62632.                           Description
  62633.  
  62634. The extended function randomx(x) produces sequences of pseudorandom
  62635. integral values in the range 1 ≤ randomx(x) ≤ (2^31 - 2).  The
  62636. extended variable *x must be initialized to an integral value (the
  62637. seed) in that range.  Then, repeated calls to randomx(x) will
  62638. generate a sequence of pseudorandom integral values according to
  62639. the iteration formula:
  62640.  
  62641.     *x = (7^5 * (*x)) mod (2^31 - 1).
  62642.  
  62643. Each randomx(x) call returns the next random number in the sequence
  62644. and updates the seed variable *x.
  62645.  
  62646. Results for randomx(x) are unspecified if seed values of *x are
  62647. nonintegral or outside the specified range.
  62648.  
  62649.                           Diagnostics
  62650.  
  62651. When properly invoked (seed values integral and within specified
  62652. range) randomx(x) signals no floating-point exceptions.
  62653.  
  62654. See also
  62655. Apple Numerics Manual, 2nd edition
  62656.  
  62657.  
  62658. æKY relation
  62659. æFc SANE.h
  62660. æT Function
  62661. æD relop relation(extended x,extended y);
  62662. æDT relop myVariable = relation((extended)x,(extended)y);
  62663. æC                Synopsis
  62664.  
  62665. #include <SANE.h>
  62666. relop relation(extended x,extended y);
  62667.  
  62668.                            Description
  62669.  
  62670. The function relation(x,y) returns the ordering relation [relop]
  62671. value such that "x relation y" is true.
  62672.  
  62673. If x or y is a signaling NaN, relation(x,y) returns UNORDERED and
  62674. signals invalid operation.
  62675.  
  62676.                           Diagnostics
  62677.  
  62678. The floating-point exception flag invalid operation is honored by
  62679. relation(x,y).
  62680.  
  62681. See also
  62682. relop
  62683. Apple Numerics Manual, 2nd edition
  62684.  
  62685.  
  62686. æKY remainder
  62687. æFc SANE.h
  62688. æT Function
  62689. æD extended remainder(extended x,extended y,short *quo);
  62690. æDT extended myVariable = remainder((extended)x,(extended)y,(short *)quo);
  62691. æC                Synopsis
  62692.  
  62693. #include <SANE.h>
  62694. extended remainder(extended x,extended y,short *quo);
  62695.  
  62696.                            Description
  62697.  
  62698. The function remainder(x,y,quo) returns the IEEE remainder (or
  62699. modulo), x rem y, and writes the lowest 7 bits (negated if quotient
  62700. is negative) of the integral quotient x/y to the short variable *quo.
  62701. The remainder function is useful for programming functions that
  62702. require argument reduction.
  62703.  
  62704. The IEEE remainder function differs from other commonly used
  62705. remainder and modulo functions by returning an exact result of the
  62706. smallest possible magnitude.  Other remainder functions can be
  62707. constructed from the IEEE remainder function by appropriately
  62708. adding or subtracting y.
  62709.  
  62710. Special cases for remainder(x,y,quo):
  62711.  
  62712. Invalid operation is signaled and a quiet NaN is returned if either
  62713.   x or y is a signaling NaN, if x is infinite and y is not a NaN,
  62714.   or if y is 0 and x is not a NaN.
  62715. A quiet NaN is returned and no exceptions are signaled if either x
  62716.   or y is a quiet NaN and neither x nor y is a signaling NaN.
  62717.  
  62718.                           Diagnostics
  62719.  
  62720. The floating-point exception flag invalid operation is honored by
  62721. the remainder(x,y,quo) function.
  62722.  
  62723. See also
  62724. fmod, modf
  62725. Apple Numerics Manual, 2nd edition
  62726.  
  62727.  
  62728. æKY rint
  62729. æFc SANE.h
  62730. æT Function
  62731. æD extended rint(extended x);
  62732. æDT extended myVariable = rint((extended)x);
  62733. æC                Synopsis
  62734.  
  62735. #include <SANE.h>
  62736. extended rint(extended x);
  62737.  
  62738.                            Description
  62739.  
  62740. The function rint(x) returns in extended format the result of
  62741. rounding the argument x to an integral value according to the
  62742. current rounding direction.
  62743.  
  62744. Special cases for rint(x):
  62745.  
  62746. If x is a NaN, rint(x) returns a quiet NaN; if x is a signaling NaN,
  62747.   rint(x) will also signal invalid operation.
  62748. If x has a nonzero fractional part (x is not a NaN and rint(x) != x),
  62749.   then rint(x) signals inexact.
  62750.  
  62751.                           Diagnostics
  62752.  
  62753. Two floating-point exception flags——invalid operation and inexact——
  62754. are honored by rint(x).
  62755.  
  62756. See also
  62757. ceil, floor, rounddir
  62758. Apple Numerics Manual, 2nd edition
  62759.  
  62760.  
  62761. æKY scalb
  62762. æFc SANE.h
  62763. æT Function
  62764. æD extended scalb(short n,extended x);
  62765. æDT extended myVariable = scalb((short)n,(extended)x);
  62766. æC Synopsis
  62767.  
  62768. #include <SANE.h>
  62769. extended scalb(short n,extended x);
  62770.  
  62771.                           Description
  62772.  
  62773. The function scalb(n,x) efficiently scales the operand x by the
  62774. given  [short] integer power n of 2, returning x*2^n without
  62775. calculating 2^n.
  62776.  
  62777.                           Diagnostics
  62778.  
  62779. The scalb function honors four floating-point exception flags——
  62780. invalid operation, underflow, overflow, and inexact——as prescribed
  62781. by SANE.
  62782.  
  62783. See also
  62784. ldexp, logb
  62785. Apple Numerics Manual, 2nd edition
  62786.  
  62787.  
  62788. æKY setenvironment
  62789. æFc SANE.h
  62790. æT Function
  62791. æD void setenvironment(environment e);
  62792. æDT setenvironment((environment)e);
  62793. æC Synopsis
  62794.  
  62795. #include <SANE.h>
  62796. void setenvironment(environment e);
  62797.  
  62798.                           Description
  62799.  
  62800. The function setenvironment(e) sets the current environment to e.
  62801. This function allows the user to configure the floating-point
  62802. environment by manipulating the settings for rounding direction,
  62803. rounding precision, exception flags, and halt/trap enables.
  62804.  
  62805.                           Diagnostics
  62806.  
  62807. The setenvironment function may raise or lower any of the floating-
  62808. point exception flags, but exceptions set by setenvironment do not
  62809. cause halts/traps even if they are enabled.
  62810.  
  62811. See also
  62812. environment, getenvironment, procentry, procexit
  62813. Apple Numerics Manual, 2nd edition
  62814.  
  62815.  
  62816. æKY setexception
  62817. æFc SANE.h
  62818. æT Function
  62819. æD void setexception(exception e,long s);
  62820. æDT setexception((exception)e,(long)s);
  62821. æC Synopsis
  62822.  
  62823. #include <SANE.h>
  62824. void setexception(exception e,long s);
  62825.  
  62826.                           Description
  62827.  
  62828. The function setexception(e,s) clears the e flags if s is zero or
  62829. sets the e flags otherwise.  The exception operand e is the bitwise
  62830. OR of any combination of individual exception values.  Exceptions
  62831. raised by setexception will cause enabled halts/traps to be taken.
  62832.  
  62833. In mc68881 mode, if any accrued exception bits are set in the
  62834. argument e, they are mapped into the appropriate current exception
  62835. bit(s).
  62836.  
  62837.                           Diagnostics
  62838.  
  62839. The setexception function may raise or lower any of the floating-
  62840. point exception flags.  Exceptions set by setexception do cause
  62841. enabled halts/traps to be taken, unlike the setenvironment function.
  62842.  
  62843. See also
  62844. exception, testexception, setenvironment
  62845. Apple Numerics Manual, 2nd edition
  62846.  
  62847.  
  62848. æKY sethalt
  62849. æFc SANE.h
  62850. æT Function
  62851. æD void sethalt(exception e,long s);
  62852. æDT sethalt((exception)e,(long)s);
  62853. æC Synopsis
  62854.  
  62855. #include <SANE.h>
  62856. void sethalt(exception e,long s);
  62857.  
  62858.                           Description
  62859.  
  62860. The function sethalt(e,s) disables e halts/traps if s is zero or
  62861. sets the e halts/traps otherwise.  The exception operand e is the
  62862. bitwise OR of any combination of individual exception values.
  62863.  
  62864. This function allows the enabling and disabling of floating-point
  62865. halts/traps without concerning the user with other environmental
  62866. settings.  It is the user's responsibility to ensure that enabled
  62867. halts/traps are vectored to proper handling routines for the various
  62868. exceptions.
  62869.  
  62870. In mc68881 mode, if any accrued exception bits are set in the
  62871. argument e, they are mapped into the appropriate floating-point
  62872. coprocessor trap enable(s) [or disable(s)].
  62873.  
  62874.                           Diagnostics
  62875.  
  62876. The sethalt function signals no floating-point exceptions.  Halts or
  62877. traps enabled by sethalt will be taken only when the corresponding
  62878. exceptions are signaled by subsequent floating-point operations.
  62879.  
  62880. See also
  62881. exception, haltvector, setenvironment, sethaltvector, settrapvector,
  62882.   testhalt, trapvector
  62883. Apple Numerics Manual, 2nd edition
  62884.  
  62885.  
  62886. æKY sethaltvector
  62887. æFc SANE.h
  62888. æT Function
  62889. æD #ifndef mc68881
  62890. void sethaltvector(haltvector v);
  62891. #endif
  62892. æDT sethaltvector((haltvector)v);
  62893. æC Synopsis
  62894.  
  62895. #include <SANE.h>
  62896. #ifndef mc68881
  62897. void sethaltvector(haltvector v);
  62898. #endif
  62899.  
  62900.                           Description
  62901.  
  62902. The function sethaltvector(v) vectors floating-point halt handling
  62903. to the routine pointed to by haltvector v.  This function is only
  62904. defined when the mc68881 compiler option is not selected.
  62905.  
  62906.                           Diagnostics
  62907.  
  62908. The sethaltvector function raises no floating-point exception flags.
  62909.  
  62910. See also
  62911. haltvector, gethaltvector
  62912. Apple Numerics Manual, 2nd edition
  62913.  
  62914.  
  62915. æKY setprecision
  62916. æFc SANE.h
  62917. æT Function
  62918. æD void setprecision(roundpre p);
  62919. æDT setprecision((roundpre)p);
  62920. æC Synopsis
  62921.  
  62922. #include <SANE.h>
  62923. void setprecision(roundpre p);
  62924.  
  62925.                           Description
  62926.  
  62927. The function setprecision(p) sets the floating-point rounding
  62928. precision to p.
  62929.  
  62930.                           Diagnostics
  62931.  
  62932. The setprecision function raises no floating-point exception flags.
  62933.  
  62934. See also
  62935. roundpre, getprecision, setenvironment
  62936. Apple Numerics Manual, 2nd edition
  62937.  
  62938.  
  62939. æKY setround
  62940. æFc SANE.h
  62941. æT Function
  62942. æD void setround(rounddir r);
  62943. æDT setround((rounddir)r);
  62944. æC Synopsis
  62945.  
  62946. #include <SANE.h>
  62947. void setround(rounddir r);
  62948.  
  62949.                           Description
  62950.  
  62951. The function setround(r) sets the floating-point rounding direction
  62952. to r.
  62953.  
  62954.                           Diagnostics
  62955.  
  62956. The setround function raises no floating-point exception flags.
  62957.  
  62958. See also
  62959. rounddir, getround, setenvironment
  62960. Apple Numerics Manual, 2nd edition
  62961.  
  62962.  
  62963. æKY settrapvector
  62964. æFc SANE.h
  62965. æT Function
  62966. æD #ifdef mc68881
  62967. void settrapvector(const trapvector *v);
  62968. #endif
  62969. æDT settrapvector((const trapvector *)v);
  62970. æC Synopsis
  62971.  
  62972. #include <SANE.h>
  62973. #ifdef mc68881
  62974. void settrapvector(const trapvector *v);
  62975. #endif
  62976.  
  62977.                           Description
  62978.  
  62979. The function settrapvector(v) sets the current trapvector structure
  62980. for the MC68881 math coprocessor equal to *v.  This function is
  62981. defined only if the mc68881 compiler option is selected.
  62982.  
  62983.                           Diagnostics
  62984.  
  62985. The settrapvector function raises no floating-point exception flags.
  62986.  
  62987. See also
  62988. trapvector, gettrapvector
  62989. Apple Numerics Manual, 2nd edition
  62990. MC68881/MC68882 Floating-Point Coprocessor User's Manual
  62991.  
  62992.  
  62993. æKY signnum
  62994. æFc SANE.h
  62995. æT Function
  62996. æD long signnum(extended x);
  62997. æDT long myVariable = signnum((extended)x);
  62998. æC Synopsis
  62999.  
  63000. #include <SANE.h>
  63001. long signnum(extended x);
  63002.  
  63003.                           Description
  63004.  
  63005. The long function signnum(x) returns 0 if the sign bit of x is clear
  63006. [positive] and 1 if the sign bit is set [negative].
  63007.  
  63008.                           Diagnostics
  63009.  
  63010. The signnum function raises no floating-point exceptions.
  63011.  
  63012. See also
  63013. Apple Numerics Manual, 2nd edition
  63014.  
  63015.  
  63016. æKY str2dec
  63017. æFc SANE.h
  63018. æT Function
  63019. æD void str2dec(const char *s,short *ix,decimal *d,short *vp);
  63020. æDT str2dec((const char *)s,(short *)ix,(decimal *)d,(short *)vp);
  63021. æC Synopsis
  63022.  
  63023. #include <SANE.h>
  63024. void str2dec(const char *s,short *ix,decimal *d,short *vp);
  63025.  
  63026.                           Description
  63027.  
  63028. The scanning routine str2dec(s,ix,d,vp) scans the string *s and
  63029. writes the output to decimal structure *d.  On input, the index
  63030. *ix indicates the position in the string where scanning is to begin.
  63031. On output, *ix is one greater than the index of the last character
  63032. of the longest numeric substring scanned.  The boolean short *vp
  63033. [valid prefix] on output contains 1 [true] if the entire input
  63034. string beginning at the input index is a valid numeric string or a
  63035. prefix of a valid numeric string; otherwise *vp contains 0 [false].
  63036.  
  63037.                           Diagnostics
  63038.  
  63039. The str2dec scanner raises no floating-point exception flags.
  63040.  
  63041. See also
  63042. decimal, dec2str
  63043. Apple Numerics Manual, 2nd edition
  63044.  
  63045.  
  63046. æKY testexception
  63047. æFc SANE.h
  63048. æT Function
  63049. æD long testexception(exception e);
  63050. æDT long myVariable = testexception((exception)e);
  63051. æC Synopsis
  63052.  
  63053. #include <SANE.h>
  63054. long testexception(exception e);
  63055.  
  63056.                           Description
  63057.  
  63058. The long function testexception(e) returns 1 if any e flag is set
  63059. or 0 otherwise.  The exception operand e is the bitwise OR of any
  63060. combination of individual exception values.
  63061.  
  63062.                           Diagnostics
  63063.  
  63064. The testexception function signals no floating-point exceptions.
  63065.  
  63066. See also
  63067. exception, setexception
  63068. Apple Numerics Manual, 2nd edition
  63069.  
  63070.  
  63071. æKY testhalt
  63072. æFc SANE.h
  63073. æT Function
  63074. æD long testhalt(exception e);
  63075. æDT long myVariable = testhalt((exception)e);
  63076. æC Synopsis
  63077.  
  63078. #include <SANE.h>
  63079. long testhalt(exception e);
  63080.  
  63081.                           Description
  63082.  
  63083. The long function testhalt(e) returns 1 if any halt or trap
  63084. corresponding to e is set or returns 0 otherwise.  The exception
  63085. operand e is the bitwise OR of any combination of individual
  63086. exception values.
  63087.  
  63088. In mc68881 mode, if any accrued exception bits are set in the
  63089. argument e, they are mapped into the appropriate trap enable bit(s)
  63090. for the test.
  63091.  
  63092.                           Diagnostics
  63093.  
  63094. The testhalt function signals no floating-point exceptions.
  63095.  
  63096. See also
  63097. exception, sethalt
  63098. Apple Numerics Manual, 2nd edition
  63099.  
  63100.  
  63101. æKY x80tox96
  63102. æFc SANE.h
  63103. æT Function
  63104. æD #ifdef mc68881
  63105. void x80tox96(const extended80 *x80,extended *x96);
  63106. #else
  63107. void x80tox96(const extended *x80,extended96 *x96); 
  63108. #endif
  63109. æDT #ifdef mc68881
  63110. x80tox96((const extended80 *)x80,(extended *)x96);
  63111. #else
  63112. x80tox96((const extended *)x80,(extended96 *)x96);
  63113. #endif
  63114. æC Synopsis
  63115.  
  63116. #include <SANE.h>
  63117. #ifdef mc68881
  63118. void x80tox96(const extended80 *x80,extended *x96);
  63119. #else
  63120. void x80tox96(const extended *x80,extended96 *x96); 
  63121. #endif
  63122.  
  63123.                           Description
  63124.  
  63125. The function x80tox96(x80,x96) converts the 80-bit extended number
  63126. (format for non-mc68881 mode SANE), *x80, to its 96-bit equivalent
  63127. (mc68881 mode format) and stores the result as *x96.
  63128.  
  63129.                           Diagnostics
  63130.  
  63131. The x80tox96 function signals no floating-point exceptions.
  63132.  
  63133. See also
  63134. extended80, extended96, x96tox80
  63135. Apple Numerics Manual, 2nd edition
  63136.  
  63137.  
  63138. æKY x96tox80
  63139. æFc SANE.h
  63140. æT Function
  63141. æD #ifdef mc68881
  63142. void x96tox80(const extended *x96,extended80 *x80);
  63143. #else
  63144. void x96tox80(const extended96 *x96,extended *x80); 
  63145. #endif
  63146. æDT #ifdef mc68881
  63147. x96tox80((const extended *)x96,(extended80 *)x80);
  63148. #else
  63149. x96tox80((const extended96 *)x96,(extended *)x80);
  63150. #endif
  63151. æC Synopsis
  63152.  
  63153. #include <SANE.h>
  63154. #ifdef mc68881
  63155. void x96tox80(const extended *x96,extended80 *x80);
  63156. #else
  63157. void x96tox80(const extended96 *x96,extended *x80); 
  63158. #endif
  63159.  
  63160.                           Description
  63161.  
  63162. The function x96tox80(x96,x80) converts the 96-bit extended number
  63163. (format for mc68881 mode SANE), *x96, to its 80-bit equivalent
  63164. (non-mc68881 mode format) and stores the result as *x80.
  63165.  
  63166.                           Diagnostics
  63167.  
  63168. The x96tox80 function signals no floating-point exceptions.
  63169.  
  63170. See also
  63171. extended80, extended96, x80tox96
  63172. Apple Numerics Manual, 2nd edition
  63173.  
  63174.  
  63175. æKY CURBSONUNOR
  63176. CURDIVBYZERO
  63177. CURINEX1
  63178. CURINEX2
  63179. CUROPERROR
  63180. CUROVERFLOW
  63181. CURSIGNAN
  63182. CURUNDERFLOW
  63183. æFc SANE.h
  63184. æD #ifdef mc68881
  63185.  
  63186. /* MC68881/2 current exceptions */
  63187. #define CURINEX1 ((exception)(256))
  63188. #define CURINEX2 ((exception)(512))
  63189. #define CURDIVBYZERO ((exception)(1024))
  63190. #define CURUNDERFLOW ((exception)(2048))
  63191. #define CUROVERFLOW ((exception)(4096))
  63192. #define CUROPERROR ((exception)(8192))
  63193. #define CURSIGNAN ((exception)(16384))
  63194. #define CURBSONUNOR ((exception)(32768))
  63195.  
  63196. #endif
  63197.  
  63198. æC 
  63199. See also
  63200. exception
  63201. Apple Numerics Manual, 2nd edition
  63202. MC68881/MC68882 Floating-Point Coprocessor User's Manual
  63203.  
  63204.  
  63205. æKY decform
  63206. æFc SANE.h
  63207. æD struct decform {
  63208.     char style;                    /*FLOATDECIMAL or FIXEDDECIMAL*/
  63209.     char unused;
  63210.     short digits;
  63211. };
  63212. typedef struct decform decform;
  63213.  
  63214. æC 
  63215.                           Description                          
  63216.  
  63217. The decform structure is used to control the formatting of numeric
  63218. decimal strings which are the results of conversions from SANE data
  63219. types.  The style field may take one of two values, FLOATDECIMAL or
  63220. FIXEDDECIMAL.  The value of the digits field is the number of
  63221. significant digits if style is FLOATDECIMAL or the number of digits
  63222. to the right of the decimal point if style is FIXEDDECIMAL.  Decimal
  63223. strings resulting from conversions controlled by decform structures
  63224. are always acceptable input for conversions from decimal strings to
  63225. SANE types.
  63226.  
  63227. See also
  63228. FIXEDDECIMAL, FLOATDECIMAL, dec2str, num2dec
  63229. Apple Numerics Manual, 2nd edition
  63230.  
  63231.  
  63232. æKY decimal
  63233. æFc SANE.h
  63234. æD struct decimal {
  63235.     char sgn;                           /*sign 0 for +, 1 for -*/
  63236.     char unused;
  63237.     short exp;                          /*decimal exponent*/
  63238.     struct{
  63239.         unsigned char length;
  63240.         unsigned char text[SIGDIGLEN];  /*significant digits */
  63241.         unsigned char unused;
  63242.         }sig;
  63243. };
  63244. typedef struct decimal decimal;
  63245.  
  63246. æC 
  63247.                           Description                          
  63248.  
  63249. The decimal structure provides an intermediate unpacked decimal
  63250. representation of floating-point numbers for programmers who wish
  63251. to do their own parsing of numeric input or formatting of numeric
  63252. output.  The decimal structure has three fields of import:
  63253.  
  63254.     sgn---the sign field, which is 0 for + and 1 for -;
  63255.     exp---the value of the decimal exponent;
  63256.     sig---the value of the significand expressed as a decimal
  63257.           integer in the form of a Pascal string of at most
  63258.           SIGDIGLEN characters.
  63259.  
  63260. The implied decimal point is at the right end of sig, with exp set
  63261. accordingly.  Thus, the value represented by a decimal structure is:
  63262.  
  63263.     (-1)^sgn * sig * 10^exp.
  63264.  
  63265. Zeros, infinities, and NaNs are converted to decimal structures with
  63266. sig parts "0", "I", and strings beginning with "N", respectively,
  63267. whereas exp is undefined.  For NaNs, "N" may be followed by a
  63268. hexadecimal representation of the input significand.  The third and
  63269. fourth hex digits following the N give the NaN code.  For example,
  63270. the sig field (Pascal string) "N4021000000000000" corresponds to
  63271. a (quiet) NaN with code value $21.
  63272.  
  63273. See also
  63274. dec2num, dec2str, num2dec, str2dec, SIGDIGLEN
  63275. Apple Numerics Manual, 2nd edition
  63276.  
  63277.  
  63278. æKY DIVBYZERO
  63279. INEXACT
  63280. INVALID
  63281. OVERFLOW
  63282. UNDERFLOW
  63283. æFc SANE.h
  63284. æD #ifdef mc68881
  63285.  
  63286. /* MC68881/2 accrued exceptions */
  63287. #define INEXACT ((exception)(8))
  63288. #define DIVBYZERO ((exception)(16))
  63289. #define UNDERFLOW ((exception)(32))
  63290. #define OVERFLOW ((exception)(64))
  63291. #define INVALID ((exception)(128))
  63292.  
  63293. #else
  63294.  
  63295. /* SANE (IEEE) exceptions */
  63296. #define INVALID ((exception)(1))
  63297. #define UNDERFLOW ((exception)(2))
  63298. #define OVERFLOW ((exception)(4))
  63299. #define DIVBYZERO ((exception)(8))
  63300. #define INEXACT ((exception)(16))
  63301.  
  63302. #endif
  63303.  
  63304. æC 
  63305. See also
  63306. exception
  63307. Apple Numerics Manual, 2nd edition
  63308. MC68881/MC68882 Floating-Point Coprocessor User's Manual
  63309.  
  63310.  
  63311. æKY environment
  63312. æFc SANE.h
  63313. æD #ifdef mc68881
  63314. struct environment {
  63315.     long FPCR;
  63316.     long FPSR;
  63317. };
  63318. typedef struct environment environment;
  63319. #else
  63320. typedef short environment;
  63321. #endif
  63322.  
  63323. æC 
  63324.                           Description
  63325.  
  63326. The environment type allows the user to query or set the floating-
  63327. point environment controls, which include rounding direction,
  63328. rounding precision, exception flags, and halt/trap settings.
  63329.  
  63330. In non-mc68881 mode, environmental controls and flags occupy 14 bits
  63331. of short storage.  The current floating-point environment is main-
  63332. tained by the system and is accessed by the user via the functions
  63333. getenvironment and setenvironment.
  63334.  
  63335. In mc68881 mode, the environment type is a structure consisting of
  63336. two longs.  This structure corresponds to the control (FPCR) and
  63337. status (FPSR) registers of the math coprocessor, which maintain
  63338. the current floating-point environment.  The user may access the
  63339. environment via the functions getenvironment and setenvironment.
  63340.  
  63341. See also
  63342. IEEEDEFAULTENV, getenvironment, procentry, procexit, setenvironment
  63343. Apple Numerics Manual, 2nd edition
  63344. MC68881/MC68882 Floating-Point Coprocessor User's Manual
  63345.  
  63346.  
  63347. æKY exception
  63348. æFc SANE.h
  63349. æD #ifdef mc68881
  63350. typedef long exception;
  63351. #else
  63352. typedef short exception
  63353. #endif
  63354.  
  63355. æC 
  63356.                           Description
  63357.                           
  63358. The exception data type contains the exception flag status for a
  63359. floating-point environment.  The exception types for mc68881 mode
  63360. and non-mc68881 mode are quite different.
  63361.  
  63362. In non-mc68881 (software SANE) mode, the exception type is short.
  63363. In this mode, there are five exception flags, corresponding to the
  63364. five exceptions in the IEEE floating-point standard.  The value of
  63365. an exception word may be zero or the combination (sum or logical OR)
  63366. of any combination of the five exception flag values.  Halt handling
  63367. may be done on any of the five exception conditions as they are
  63368. detected during a floating-point operaton by the SANE engine.
  63369. Exception flags that are set remain so until cleared by the user.
  63370. The values for the individual flags are:
  63371.  
  63372.     DIVBYZERO---divide-by-zero condition;
  63373.     INEXACT---inexact condition;
  63374.     INVALID---invalid operation;
  63375.     OVERFLOW---overflow condition; and
  63376.     UNDERFLOW---underflow condition.
  63377.  
  63378. In mc68881 mode, the exception type is long, and there are 13
  63379. exception flags divided into two groups.  The five IEEE exceptions
  63380. (DIVBYZERO, INEXACT, INVALID, OVERFLOW, and UNDERFLOW) are accrued
  63381. (sticky) flags.  When set, they remain set until cleared by the user.
  63382. No trapping may take place on the setting of accrued exceptions.
  63383. The remaining eight exception flags are the current exceptions,
  63384. which reflect the status of the last MC68881/2 instruction.  They
  63385. are cleared at the start of each coprocessor instruction.  The
  63386. values for the current exception flags are:
  63387.  
  63388.     CURINEX1---inexact result on packed decimal input to coprocessor;
  63389.     CURINEX2---other inexact results;
  63390.     CURDIVBYZERO---divide-by-zero condition (or infinite asymptote);
  63391.     CURUNDERFLOW---underflow condition;
  63392.     CUROVERFLOW---overflow condition;
  63393.     CUROPERROR---operand error;
  63394.     CURSIGNAN---signaling NaN input; and
  63395.     CURBSONUNOR---branch/set on unordered condition.
  63396.  
  63397. The MC68881/2 floating-point coprocessor allows trapping to handlers
  63398. when any of the current exceptions is signaled.
  63399.  
  63400. In either software SANE or mc68881 mode, halts/traps are enabled
  63401. or disabled via the sethalt function and tested by the testhalt
  63402. function.  Exceptions may be set or cleared using the setenvironment
  63403. function, but, in this case, trapping to enabled handler code is
  63404. never invoked.  The setexception function sets or clears an
  63405. arbitrary exception pattern.  Exceptions set by setexception will
  63406. trap to handler code if enabled.  Exception state is tested by the
  63407. testexception function.
  63408.  
  63409. In mc68881 mode, the functions sethalt, testhalt, setexception, and
  63410. procexit map any accrued exception bits which are set in their
  63411. arguments into the appropriate corresponding current exception
  63412. (or trap-enable) bits as follows:
  63413.  
  63414.     INVALID -> CUROPERROR + CURSIGNAN + CURBSONUNOR;
  63415.     UNDERFLOW -> CURUNDERFLOW;
  63416.     OVERFLOW -> CUROVERFLOW;
  63417.     DIVBYZERO -> CURDIVBYZERO; and
  63418.     INEXACT -> CURINEX1 + CURINEX2.
  63419.  
  63420. See also
  63421. setexception, sethalt, testexception, testhalt
  63422. DIVBYZERO, INEXACT, INVALID, OVERFLOW, UNDERFLOW
  63423. CURBSONUNOR, CURDIVBYZERO, CURINEX1, CURINEX2, CUROPERROR, CUROVERFLOW,
  63424.     CURSIGNAN, CURUNDERFLOW
  63425. Apple Numerics Manual, 2nd edition
  63426. MC68881/MC68882 Floating-Point Coprocessor User's Manual
  63427.  
  63428.  
  63429. æKY extended80
  63430. æFc SANE.h
  63431. æD #ifdef mc68881
  63432. struct extended80 {
  63433.     short w[5];
  63434. };
  63435. typedef struct extended80 extended80;
  63436. #endif
  63437.  
  63438. æC 
  63439.                           Description
  63440.                           
  63441. In mc68881 mode, the extended80 structure is provided to enable
  63442. binary-to-binary conversions between the native 96-bit extended
  63443. type and the 80-bit extended type of the non-mc68881 mode.  Two
  63444. conversion functions, x80tox96 and x96tox80, support the
  63445. extended80 structure.  No arithmetic functions are provided to
  63446. support the extended80 structure in mc68881 mode.  
  63447.  
  63448. See also
  63449. x80tox96, x96tox80
  63450. Apple Numerics Manual, 2nd edition
  63451.  
  63452.  
  63453. æKY extended96
  63454. æFc SANE.h
  63455. æD #ifndef mc68881
  63456. typedef struct {short w[6];} extended96;
  63457. #endif
  63458.  
  63459. æC 
  63460.                           Description
  63461.                           
  63462. In non-mc68881 mode, the extended96 structure is provided to enable
  63463. binary-to-binary conversions between the native 80-bit extended
  63464. type and the 96-bit extended type of the mc68881 mode.  Two
  63465. conversion functions, x80tox96 and x96tox80, support the extended96
  63466. structure.  No arithmetic functions are provided to support the
  63467. extended96 structure in non-mc68881 mode.  
  63468.  
  63469. See also
  63470. x80tox96, x96tox80
  63471. Apple Numerics Manual, 2nd edition
  63472.  
  63473.  
  63474. æKY EXTPRECISION
  63475. DBLPRECISION
  63476. FLOATPRECISION
  63477. æFc SANE.h
  63478. æD /* Rounding Precisions */
  63479.  
  63480. #define EXTPRECISION ((roundpre)(0))
  63481. #define DBLPRECISION ((roundpre)(1))
  63482. #define FLOATPRECISION ((roundpre)(2))
  63483.  
  63484. æC 
  63485. See also
  63486. roundpre, getprecision, setprecision
  63487. Apple Numerics Manual, 2nd edition
  63488.  
  63489.  
  63490. æKY FLOATDECIMAL
  63491. FIXEDDECIMAL
  63492. æFc SANE.h
  63493. æD /* Decimal Formatting Styles */
  63494.  
  63495. #define FLOATDECIMAL ((char)(0))
  63496. #define FIXEDDECIMAL ((char)(1))
  63497.  
  63498. æC 
  63499. See also
  63500. decform
  63501. Apple Numerics Manual, 2nd edition
  63502.  
  63503.  
  63504. æKY GREATERTHAN
  63505. LESSTHAN
  63506. EQUALTO
  63507. UNORDERED
  63508. æFc SANE.h
  63509. æD /* Ordering Relations */
  63510.  
  63511. #define GREATERTHAN ((relop)(0))
  63512. #define LESSTHAN ((relop)(1))
  63513. #define EQUALTO ((relop)(2))
  63514. #define UNORDERED ((relop)(3))
  63515.  
  63516. æC 
  63517. See also
  63518. relop, relation
  63519. Apple Numerics Manual, 2nd edition
  63520.  
  63521.  
  63522. æKY haltvector
  63523. æFc SANE.h
  63524. æD #ifndef mc68881
  63525. typedef pascal void (*haltvector)(mischaltinfo *misc, void *src2,
  63526.                              void *src, void *dst, short opcode);
  63527. #endif
  63528.  
  63529. æC 
  63530.                           Description                          
  63531.  
  63532. The haltvector is defined only in non-mc68881 mode.  It is a
  63533. pointer to a halt handling routine which is written to behave
  63534. like a Pascal procedure.  When an exception that is halt-enabled
  63535. occurs, the SANE engine passes some of the floating-point state
  63536. to the halt handler pointed to by the haltvector.  The five
  63537. parameters are pushed on the stack are in the following order:
  63538.     
  63539.     1.    address of mischaltinfo record;
  63540.     2.    address of SRC2 operand (undefined longword if no SRC2);
  63541.     3.  address of SRC operand (undefined longword if no SRC);
  63542.     4.  address of DST operand; and
  63543.     5.  SANE engine opcode for floating-point operation which
  63544.         caused the halt condition.
  63545.  
  63546. The halt handler is called like a subroutine (via a JSR instruction)
  63547. and is expected to pop all of the stack arguments just like a
  63548. Pascal procedure.
  63549.  
  63550. In order to have specific handler code executed when exceptional
  63551. conditions arise, the user must enable the appropriate halts via
  63552. the sethalt function and must vector the halts to his handler
  63553. code by using the sethaltvector function (with a pointer to his
  63554. halthandler as the argument).  The gethaltvector function returns
  63555. the current haltvector.
  63556.  
  63557. See also 
  63558. gethaltvector, mischaltinfo, sethaltvector
  63559. Apple Numerics Manual, 2nd edition
  63560.  
  63561.  
  63562. æKY IEEEDEFAULTENV
  63563. æFc SANE.h
  63564. æD #ifdef mc68881
  63565. environment IEEEDEFAULTENV = {0L,0L};
  63566. #else
  63567. #define IEEEDEFAULTENV ((environment)(0))
  63568. #endif
  63569.  
  63570. æC 
  63571.                           Description
  63572.  
  63573. The environment constant IEEEDEFAULTENV describes the initial
  63574. floating-point compilation and runtime environments.  When the
  63575. environment is set to IEEEDEFAULTENV, the various controls and
  63576. flags are set as follows:
  63577.  
  63578.     rounding precision is to extended precision;
  63579.     rounding direction is to nearest;
  63580.     halts/traps are disabled; and
  63581.     all exception flags are cleared.
  63582.  
  63583. The default environment represented by IEEEDEFAULTENV may be set
  63584. at any time via the function call setenvironment(IEEEDEFAULTENV).
  63585. It is also the floating-point environment set by procentry.
  63586.  
  63587. See also
  63588. environment, procentry, setenvironment
  63589. Apple Numerics Manual, 2nd edition
  63590.  
  63591.  
  63592. æKY mischaltinfo
  63593. æFc SANE.h
  63594. æD #ifndef mc68881
  63595. struct mischaltinfo {
  63596.     unsigned short haltexceptions;
  63597.     unsigned short pendingCCR;
  63598.     long pendingD0;
  63599. };
  63600. typedef struct mischaltinfo mischaltinfo;
  63601. #endif
  63602.  
  63603. æC 
  63604.                           Description
  63605.  
  63606. In non-mc68881 mode, the mischaltinfo structure is prepared by the
  63607. halt-handling mechanism of the SANE engine to provide the user's
  63608. halt handler routine with some state information.  When an exception
  63609. that is halt-enabled occurs, the halt handler receives as one of its
  63610. parameters the address of the mischaltinfo structure.  The fields
  63611. of the structure contain the following information:
  63612.  
  63613.     haltexceptions---the five low-order bits contain the bitwise
  63614.         AND of the halt-enable bits with the exceptions that
  63615.         occurred in the operation just completing;
  63616.     pendingCCR---the value of the condition code register (CCR) of
  63617.         the CPU which would have been returned by the exceptional
  63618.         operation if the halt were not enabled; and
  63619.     pendingD0---the value that CPU register D0 would have upon return
  63620.         from the operation if the halt were not enabled.
  63621.  
  63622. See also
  63623. haltvector
  63624. Apple Numerics Manual, 2nd edition
  63625.  
  63626.  
  63627. æKY numclass
  63628. æFc SANE.h
  63629. æD typedef short numclass;                 /* inquiry class */
  63630.  
  63631. æC 
  63632.                           Description                          
  63633.  
  63634. The inquiry class type numclass is returned by various SANE
  63635. functions which classify floating-point numbers.  Six numclass
  63636. values are defined:
  63637.  
  63638.     DENORMALNUM---for numbers which are subnormal in value;
  63639.     INFINITE---for numbers which are equal to ±∞;
  63640.     NORMALNUM---for normalized or normalizable values;
  63641.     QNAN---for quiet NaNs;
  63642.     SNAN---for signaling NaNs; and
  63643.     ZERONUM---for [±] zero values.
  63644.  
  63645. See also
  63646. classcomp, classdouble, classextended, classfloat
  63647. DENORMALNUM, INFINITE, NORMALNUM, QNAN, SNAN, ZERONUM
  63648. Apple Numerics Manual, 2nd edition
  63649.  
  63650.  
  63651. æKY relop
  63652. æFc SANE.h
  63653. æD typedef short relop;                    /* relational operator */
  63654.  
  63655. æC 
  63656.                           Description                          
  63657.  
  63658. The relational operator type relop is returned by the function
  63659. relation(x,y).  It may take on one of four values:
  63660.  
  63661.     GREATERTHAN---for x > y;
  63662.     LESSTHAN---for x < y;
  63663.     EQUALTO---for x = y; and
  63664.     UNORDERED---for unordered comparison [x is NaN, y is a NaN,
  63665.         or both x and y are NaNs].
  63666.  
  63667. See also
  63668. relation
  63669. EQUALTO, GREATERTHAN, LESSTHAN, UNORDERED
  63670. Apple Numerics Manual, 2nd edition
  63671.  
  63672.  
  63673. æKY rounddir
  63674. æFc SANE.h
  63675. æD typedef short rounddir;                 /* rounding direction */
  63676.  
  63677. æC 
  63678.                           Description                          
  63679.  
  63680. The rounding direction type rounddir is used by functions getround
  63681. and setround to access the floating-point rounding direction mode in
  63682. the environment.  Only four values are meaningful for this type:
  63683.  
  63684.     TONEAREST---IEEE round to nearest [default rounding];
  63685.     UPWARD---round toward +∞;
  63686.     DOWNWARD---round toward -∞; and
  63687.     TOWARDZERO---round toward zero [truncate].
  63688.  
  63689. The rounding direction affects all conversions except those between
  63690. decimal structures and decimal strings and all arithmetic operations
  63691. except remainder.
  63692.  
  63693. See also
  63694. getround, setround
  63695. DOWNWARD, TONEAREST, TOWARDZERO, UPWARD
  63696. Apple Numerics Manual, 2nd edition
  63697.  
  63698.  
  63699. æKY roundpre
  63700. æFc SANE.h
  63701. æD typedef short roundpre;                 /* rounding precision */
  63702.  
  63703. æC 
  63704.                           Description                          
  63705.  
  63706. The rounding precision type roundpre is used by functions
  63707. getprecision and setprecison to access the floating-point rounding
  63708. precision in the environment.  Only three values are meaningful for
  63709. this type:
  63710.  
  63711.     EXTPRECISION---extended precision [default];
  63712.     DBLPRECISION---double precision; and
  63713.     FLOATPRECISION---float [single] precision.
  63714.  
  63715. Normally, floating-point computations produce results to extended
  63716. precision and range.  To facilitate simulations of arithmetic
  63717. systems that are not extended-based, the user may set the rounding
  63718. precision to float or double.  In those cases, all arithmetic
  63719. operations produce results that are correctly rounded to the
  63720. narrower precision and that overflow or underflow as if the 
  63721. destination were of the narrower precision, even though results are
  63722. typically delivered to extended formats.
  63723.  
  63724. See also
  63725. getprecision, setprecision
  63726. DBLPRECISION, EXTPRECISION, FLOATPRECISION
  63727. Apple Numerics Manual, 2nd edition
  63728.  
  63729.  
  63730. æKY SIGDIGLEN
  63731. DECSTROUTLEN
  63732. æFc SANE.h
  63733. æD /* Decimal Representation Constants */
  63734.  
  63735. #define SIGDIGLEN 20            /* significant decimal digits */
  63736. #define DECSTROUTLEN 80            /* max length for dec2str output */
  63737.  
  63738. æC 
  63739.                           Description
  63740.  
  63741. The decimal representation constant SIGDIGLEN is the maximum
  63742. character length of the sig field (Pascal string) in a decimal
  63743. structure.
  63744.  
  63745. The constant DECSTROUTLEN is the maximum length for an output string
  63746. resulting from a dec2str conversion.
  63747.  
  63748. See also
  63749. decform, decimal, dec2str, num2dec
  63750. Apple Numerics Manual, 2nd edition
  63751.  
  63752.  
  63753. æKY SNAN
  63754. QNAN
  63755. INFINITE
  63756. ZERONUM
  63757. NORMALNUM
  63758. DENORMALNUM
  63759. æFc SANE.h
  63760. æD /* Inquiry Classes */
  63761.  
  63762. #define SNAN ((numclass)(0))
  63763. #define QNAN ((numclass)(1))
  63764. #define INFINITE ((numclass)(2))
  63765. #define ZERONUM ((numclass)(3))
  63766. #define NORMALNUM ((numclass)(4))
  63767. #define DENORMALNUM ((numclass)(5))
  63768.  
  63769. æC 
  63770. See also
  63771. numclass, classcomp, classdouble, classextended, classfloat
  63772. Apple Numerics Manual, 2nd edition
  63773.  
  63774.  
  63775. æKY TONEAREST
  63776. UPWARD
  63777. DOWNWARD
  63778. TOWARDZERO
  63779. æFc SANE.h
  63780. æD /* Rounding Directions */
  63781.  
  63782. #define TONEAREST ((rounddir)(0))
  63783. #define UPWARD ((rounddir)(1))
  63784. #define DOWNWARD ((rounddir)(2))
  63785. #define TOWARDZERO ((rounddir)(3))
  63786.  
  63787. æC 
  63788. See also
  63789. rounddir, getround, setround
  63790. Apple Numerics Manual, 2nd edition
  63791.  
  63792.  
  63793. æKY trapvector
  63794. æFc SANE.h
  63795. æD #ifdef mc68881
  63796. struct trapvector {
  63797.     void (*unordered)();
  63798.     void (*inexact)();
  63799.     void (*divbyzero)();
  63800.     void (*underflow)();
  63801.     void (*operror)();
  63802.     void (*overflow)();
  63803.     void (*signan)();
  63804. };
  63805. typedef struct trapvector trapvector;
  63806. #endif
  63807.  
  63808. æC 
  63809.                           Description                          
  63810.  
  63811. The trapvector structure is defined only in mc68881 mode.  It
  63812. consists of the addresses of trap-handling code for the seven
  63813. floating-point exception conditions which may be trap-enabled:
  63814.  
  63815.     unordered---branch or set on unordered condition;
  63816.     inexact---inexact result from operation or conversion from
  63817.               decimal input on the math coprocessor (CURINEX2 or
  63818.               CURINEX1 conditions, respectively);
  63819.     divbyzero---divide-by-zero condition;
  63820.     underflow---underflow condition;
  63821.     operror---invalid operand error;
  63822.     overflow---overflow condition; and
  63823.     signan---signaling NaN input.
  63824.  
  63825. In order to have specific handler code executed when exceptional
  63826. conditions arise, the user must enable the appropriate traps via
  63827. the sethalt function and must vector the exceptions to his handler
  63828. code by using the settrapvector function with an appropriately
  63829. initialized trapvector record as its argument.  The gettrapvector
  63830. function returns the current trapvector.
  63831.  
  63832. See also 
  63833. exception, gettrapvector, settrapvector
  63834. Apple Numerics Manual, 2nd edition
  63835. MC68881/MC68882 Floating-Point Coprocessor User's Manual
  63836.  
  63837.  
  63838.  
  63839. æKY Scrap.h
  63840. æKL GetScrap
  63841. InfoScrap
  63842. LoadScrap
  63843. PutScrap
  63844. UnloadScrap
  63845. ZeroScrap
  63846.  
  63847. PScrapStuff
  63848. ScrapStuff
  63849.  
  63850. æKY ScrapStuff
  63851. PScrapStuff
  63852. æFc Scrap.h
  63853. æT struct
  63854. æD struct ScrapStuff {
  63855.     long scrapSize;
  63856.     Handle scrapHandle;
  63857.     short scrapCount;
  63858.     short scrapState;
  63859.     StringPtr scrapName;
  63860. };
  63861.  
  63862. typedef struct ScrapStuff ScrapStuff;
  63863. typedef ScrapStuff *PScrapStuff;
  63864.  
  63865. æC 
  63866.  
  63867. æKY InfoScrap
  63868. æFc Scrap.h
  63869. æT Function
  63870. æTN A9F9
  63871. æD pascal PScrapStuff InfoScrap(void)
  63872.     = 0xA9F9; 
  63873. æDT PScrapStuff myVariable = InfoScrap()(void);
  63874. æRI I-457
  63875. æC 
  63876. InfoScrap returns a pointer to information about the desk scrap. The PScrapStuff data
  63877. type is defined as follows:
  63878.  
  63879. TYPE  PScrapStuff = ^ScrapStuff;
  63880.       ScrapStuff  = RECORD
  63881.                       scrapSize:    LONGINT;   {size of desk scrap}
  63882.                       scrapHandle:  Handle;    {handle to desk scrap}
  63883.                       scrapCount:   INTEGER;   {count changed by ZeroScrap}
  63884.                       scrapState:   INTEGER;   {tells where desk scrap is}
  63885.                       scrapName:    StringPtr  {scrap file name}
  63886.                     END;
  63887.  
  63888. ScrapSize is the size of the desk scrap in bytes. ScrapHandle is a handle to the
  63889. scrap if it’s in memory, or NIL if not.
  63890.  
  63891. ScrapCount is a count that changes every time ZeroScrap is called. You can use this
  63892. count for testing whether the contents of the desk scrap have changed, since if
  63893. ZeroScrap has been called, presumably PutScrap was also called. This may be useful if
  63894. your application supports display of the Clipboard or has a private scrap (as described
  63895. under “Private Scraps”, below).
  63896.  
  63897. Warning:  Just check to see whether the value of the scrapCount field has
  63898.           changed; don’t rely on exactly how it has changed.
  63899.  
  63900. ScrapState is positive if the desk scrap is in memory, 0 if it’s on the disk, or
  63901. negative if it hasn’t been initialized by ZeroScrap.
  63902.  
  63903. Note:  ScrapState is actually 0 if the scrap should be on the disk; for
  63904.        instance, if the user deletes the Clipboard file and then cuts
  63905.        something, the scrap is really in memory, but ScrapState will be 0.
  63906.  
  63907. ScrapName is a pointer to the name of the scrap file, usually “Clipboard File”.
  63908.  
  63909. Note:  InfoScrap assumes that the scrap file has a version number of 0 and is
  63910.        on the default volume. (Version numbers and volumes are described in
  63911.        the File Manager chapter.)
  63912.  
  63913. Assembly-language note:  The scrap information is available in global variables
  63914.                          that have the same names as the Pascal fields.
  63915.  
  63916. æKY UnloadScrap
  63917. æFc Scrap.h
  63918. æT Function
  63919. æTN A9FA
  63920. æD pascal long UnloadScrap(void)
  63921.     = 0xA9FA; 
  63922. æDT long myVariable = UnloadScrap()(void);
  63923. æMM
  63924. æRI I-458
  63925. æC  
  63926. Assembly-language note:  The macro you invoke to call UnloadScrap from assembly
  63927.                          language is named _UnlodeScrap.
  63928.  
  63929. UnloadScrap writes the desk scrap from memory to the scrap file, and releases the
  63930. memory it occupied. If the desk scrap is already on the disk, UnloadScrap does nothing.
  63931. If no error occurs, UnloadScrap returns the result code noErr; otherwise, it returns
  63932. an Operating System result code indicating an error.
  63933.  
  63934. æKY LoadScrap
  63935. æFc Scrap.h
  63936. æT Function
  63937. æTN A9FB
  63938. æD pascal long LoadScrap(void)
  63939.     = 0xA9FB; 
  63940. æDT long myVariable = LoadScrap()(void);
  63941. æMM
  63942. æRI I-458
  63943. æC 
  63944. Assembly-language note:  The macro you invoke to call LoadScrap from assembly
  63945.                          language is named _LodeScrap.
  63946.  
  63947. LoadScrap reads the desk scrap from the scrap file into memory. If the desk scrap is
  63948. already in memory, it does nothing. If no error occurs, LoadScrap returns the result
  63949. code noErr; otherwise, it returns an Operating System result code indicating an
  63950. error.
  63951.  
  63952. æKY GetScrap
  63953. æFc Scrap.h
  63954. æT Function
  63955. æTN A9FD
  63956. æD pascal long GetScrap(Handle hDest,ResType theType,long *offset)
  63957.     = 0xA9FD; 
  63958. æDT long myVariable = GetScrap((Handle) hDest,(ResType) theType,(long *) offset);
  63959. æMM
  63960. æRI I-459
  63961. æC  
  63962. Given an existing handle in hDest, GetScrap reads the data of type theType from the
  63963. desk scrap (whether in memory or on the disk), makes a copy of it in memory, and sets
  63964. hDest to be a handle to the copy. Usually you’ll pass in hDest a handle to a minimum-size
  63965. block; GetScrap will resize the block and copy the scrap into it. If you pass NIL in
  63966. hDest, GetScrap will not read in the data. This is useful if you want to be sure the
  63967. data is there before allocating space for its handle, or if you just want to know the
  63968. size of the data.
  63969.  
  63970. In the offset parameter, GetScrap returns the location of the data as an offset (in
  63971. bytes) from the beginning of the desk scrap. If no error occurs, the function result
  63972. is the length of the data in bytes; otherwise, it’s either an appropriate Operating
  63973. System result code (which will be negative) or the following Scrap Manager result
  63974. code:
  63975.  
  63976. CONST noTypeErr = -102; {no data of the requested type}
  63977.  
  63978. For example, given the declarations
  63979.  
  63980.   VAR  pHndl:   Handle;    {handle for 'PICT' type}
  63981.        tHndl:   Handle;    {handle for 'TEXT' type}
  63982.        length:  LONGINT;
  63983.        offset:  LONGINT;
  63984.        frame:   Rect;
  63985.  
  63986. you can make the following calls:
  63987.  
  63988.   pHndl := NewHandle(0);
  63989.   length := GetScrap(pHndl,'PICT',offset);
  63990.   IF length < 0
  63991.      THEN
  63992.          {error handling}
  63993.      ELSE DrawPicture(PicHandle(pHndl),frame)
  63994.  
  63995. If your application wants data in the form of a picture, and the scrap contains only
  63996. text, you can convert the text into a picture by doing the following:
  63997.  
  63998.   tHndl := NewHandle(0);
  63999.   length := GetScrap(tHndl,'TEXT',offset);
  64000.   IF length < 0
  64001.       THEN
  64002.           {error handling}
  64003.       ELSE
  64004.           BEGIN
  64005.           HLock(tHndl);
  64006.           pHndl := OpenPicture(thePort^.portRect);
  64007.           TextBox(tHndl^,length,thePort^.portRect,teJustLeft);
  64008.           ClosePicture;
  64009.           HUnlock(tHndl);
  64010.           END
  64011.  
  64012. The Memory Manager procedures HLock and HUnlock are used to lock and unlock blocks
  64013. when handles are dereferenced (see the Memory Manager chapter).
  64014.  
  64015. Note:  To copy the desk scrap to the TextEdit scrap, use the TextEdit
  64016.        function TEFromScrap.
  64017.  
  64018. Your application should pass its preferred data type to GetScrap. If it doesn’t
  64019. prefer one data type over any other, it should try getting each of the types it can
  64020. read, and use the type that returns the lowest offset. (A lower offset means that
  64021. this data type was written before the others, and therefore was preferred by the
  64022. application that wrote it.)
  64023.  
  64024. Note:  If you’re trying to read in a complicated picture, and there isn’t
  64025.        enough room in memory for a copy of it, you can customize QuickDraw’s
  64026.        picture retrieval so that DrawPicture will read the picture directly
  64027.        from the scrap file. (QuickDraw also lets you customize how pictures
  64028.        are saved so you can save them in a file; see the QuickDraw chapter
  64029.        for details about customizing.)
  64030.  
  64031. Note:  
  64032.  
  64033.     When reading in a picture from the scrap, allow a buffer
  64034.     of about 3.5K bytes.  (There's a convention that the
  64035.     application defining the picture won't call the QuickDraw
  64036.     procedure CopyBits for more than 3K, so a 3.5K buffer
  64037.     should be large enough for any picture.  This limit doesn't apply
  64038.     in 128K and newer ROMs.
  64039.  
  64040. æKY ZeroScrap
  64041. æFc Scrap.h
  64042. æT Function
  64043. æTN A9FC
  64044. æD pascal long ZeroScrap(void)
  64045.     = 0xA9FC; 
  64046. æDT long myVariable = ZeroScrap()(void);
  64047. æMM
  64048. æRT 180
  64049. æRI I-458
  64050. æC 
  64051. If the scrap already exists (in memory or on the disk), ZeroScrap clears its contents;
  64052. if not, the scrap is initialized in memory. You must call ZeroScrap before the first
  64053. time you call PutScrap. If no error occurs, ZeroScrap returns the result code noErr;
  64054. otherwise, it returns an Operating System result code indicating an error.
  64055.  
  64056. ZeroScrap also changes the scrapCount field of the record of information provided by
  64057. InfoScrap.
  64058.  
  64059. æKY PutScrap
  64060. æFc Scrap.h
  64061. æT Function
  64062. æTN A9FE
  64063. æD pascal long PutScrap(long length,ResType theType,Ptr source)
  64064.     = 0xA9FE; 
  64065. æDT long myVariable = PutScrap((long) length,(ResType) theType,(Ptr) source);
  64066. æMM
  64067. æRT 180
  64068. æRI I-459
  64069. æC  
  64070. PutScrap writes the data pointed to by the source parameter to the desk scrap
  64071. (in memory or on the disk). The length parameter indicates the number of bytes to
  64072. write, and theType is the data type.
  64073.  
  64074. Warning:  The specified type must be different from the type of any data
  64075.           already in the desk scrap. If you write data of a type already in
  64076.           the scrap, the new data will be appended to the scrap, and subsequent
  64077.           GetScrap calls will still return the old data.
  64078.  
  64079. If no error occurs, PutScrap returns the result code noErr; otherwise, it returns an
  64080. Operating System result code indicating an error, or the following Scrap Manager
  64081. result code:
  64082.  
  64083. CONST noScrapErr = -100; {desk scrap isn't initialized}
  64084.  
  64085. Warning:  Don’t forget to call ZeroScrap to initialize the scrap or clear its
  64086.           previous contents.
  64087.  
  64088. Note:  To copy the TextEdit scrap to the desk scrap, use the TextEdit function
  64089.        TEToScrap.
  64090.  
  64091.  
  64092. æKY Script.h
  64093. æKL Char2Pixel
  64094. CharByte
  64095. CharType
  64096. DrawJust
  64097. FindScriptRun
  64098. FindWord
  64099. Font2Script
  64100. FontScript
  64101. Format2Str
  64102. FormatStr2X
  64103. FormatX2Str
  64104. GetAppFont
  64105. GetDefFontSize
  64106. GetEnvirons
  64107. GetFormatOrder
  64108. GetMBarHeight
  64109. GetScript
  64110. GetSysFont
  64111. GetSysJust
  64112. HiliteText
  64113. InitDateCache
  64114. IntlScript
  64115. IntlTokenize
  64116. KeyScript
  64117. LongDate2Secs
  64118. LongSecs2Date
  64119. LowerText
  64120. LwrText
  64121. MeasureJust
  64122. NChar2Pixel
  64123. NDrawJust
  64124. NFindWord
  64125. NMeasureJust
  64126. NPixel2Char
  64127. NPortionText
  64128. ParseTable
  64129. Pixel2Char
  64130. PortionText
  64131. ReadLocation
  64132. ReplaceText
  64133. SetEnvirons
  64134. SetScript
  64135. SetSysJust
  64136. Str2Format
  64137. String2Date
  64138. String2Time
  64139. StripText
  64140. StripUpperText
  64141. StyledLineBreak
  64142. ToggleDate
  64143. Transliterate
  64144. TruncString
  64145. TruncText
  64146. UpperText
  64147. UprText
  64148. ValidDate
  64149. VisibleLength
  64150. WriteLocation
  64151.  
  64152. acuteUprA
  64153. acuteUprI
  64154. acuteUprO
  64155. acuteUprU
  64156. appleLogo
  64157. badDelim
  64158. badEnding
  64159. baseDblQuote
  64160. baseSingQuote
  64161. BreakTable
  64162. BreakTablePtr
  64163. breve
  64164. calArabicCivil
  64165. calArabicLunar
  64166. calCoptic
  64167. calGregorian
  64168. calJapanese
  64169. calJewish
  64170. cantReadUtilities
  64171. cedilla
  64172. centeredDot
  64173. CharByteTable
  64174. circumflex
  64175. circumflexUprA
  64176. circumflexUprE
  64177. circumflexUprI
  64178. circumflexUprO
  64179. circumflexUprU
  64180. crash
  64181. curNumberPartsVersion
  64182. DateCachePtr
  64183. DateCacheRecord
  64184. dateStdMask
  64185. dateTimeInvalid
  64186. dateTimeNotFound
  64187. dayField
  64188. dayMask
  64189. dayOfWeekField
  64190. dayOfWeekMask
  64191. dayOfYearField
  64192. dayOfYearMask
  64193. dblDagger
  64194. delimPad
  64195. diaeresisUprE
  64196. diaeresisUprI
  64197. diaeresisUprY
  64198. dotlessLwrI
  64199. doubleAcute
  64200. eraField
  64201. eraMask
  64202. extraneousStrings
  64203. fatalDateTime
  64204. fBadPartsTable
  64205. fBestGuess
  64206. fEmptyFormatString
  64207. fExtraDecimal
  64208. fExtraExp
  64209. fExtraPercent
  64210. fExtraSeparator
  64211. fFormatOK
  64212. fFormatOverflow
  64213. fFormStrIsNAN
  64214. fieldOrderNotIntl
  64215. fiLigature
  64216. flLigature
  64217. fMissingDelimiter
  64218. fMissingLiteral
  64219. fNegative
  64220. FormatClass
  64221. FormatResultType
  64222. fOutOfSynch
  64223. fPositive
  64224. fraction
  64225. fSpuriousChars
  64226. FVector
  64227. fVNumber
  64228. fZero
  64229. genCdevRangeBit
  64230. graveUprE
  64231. graveUprI
  64232. graveUprO
  64233. graveUprU
  64234. hachek
  64235. hourField
  64236. hourMask
  64237. intArabic
  64238. intEuropean
  64239. intJapanese
  64240. intlCurrency
  64241. intOutputMask
  64242. intRoman
  64243. intWestern
  64244. Itl4Handle
  64245. Itl4Ptr
  64246. Itl4Rec
  64247. ItlbExtRecord
  64248. ItlbRecord
  64249. ItlcRecord
  64250. JustStyleCode
  64251. langArabic
  64252. langChinese
  64253. langDanish
  64254. langDutch
  64255. langEnglish
  64256. langEstonian
  64257. langFaeroese
  64258. langFarsi
  64259. langFinnish
  64260. langFrench
  64261. langGerman
  64262. langGreek
  64263. langHebrew
  64264. langHindi
  64265. langHungarian
  64266. langIcelandic
  64267. langItalian
  64268. langJapanese
  64269. langKorean
  64270. langLapponian
  64271. langLettish
  64272. langLithuanian
  64273. langMalta
  64274. langMaltese
  64275. langNorwegian
  64276. langPolish
  64277. langPortugese
  64278. langPortuguese
  64279. langRussian
  64280. langSimpChinese
  64281. langSpanish
  64282. langSwedish
  64283. langThai
  64284. langTradChinese
  64285. langTurkish
  64286. langUrdu
  64287. langYugoslavian
  64288. leftOverChars
  64289. leftSingGuillemet
  64290. LongDateCvt
  64291. LongDateField
  64292. longDateFound
  64293. LongDateRec
  64294. MachineLocation
  64295. macron
  64296. maxDateField
  64297. minuteField
  64298. minuteMask
  64299. monthField
  64300. monthMask
  64301. NBreakTable
  64302. NBreakTablePtr
  64303. NItl4Handle
  64304. NItl4Ptr
  64305. NItl4Rec
  64306. NumberParts
  64307. NumberPartsPtr
  64308. NumFormatString
  64309. OffPair
  64310. ogonek
  64311. overDot
  64312. perThousand
  64313. pmField
  64314. pmMask
  64315. res1Field
  64316. res2Field
  64317. res3Field
  64318. rightSingGuillemet
  64319. ring
  64320. romanAppFond
  64321. romanFlags
  64322. romanSysFond
  64323. ScriptRunStatus
  64324. secondField
  64325. secondMask
  64326. sepNotConsistent
  64327. sepNotIntlSep
  64328. smallDateBit
  64329. smAmharic
  64330. smArabic
  64331. smArmenian
  64332. smBadScript
  64333. smBadVerb
  64334. smBengali
  64335. smBidirect
  64336. smBreakChar
  64337. smBreakOverflow
  64338. smBreakWord
  64339. smBurmese
  64340. smcClassMask
  64341. smcDoubleMask
  64342. smChar1byte
  64343. smChar2byte
  64344. smCharAscii
  64345. smCharEuro
  64346. smCharFISGana
  64347. smCharFISGreek
  64348. smCharFISHangul
  64349. smCharFISIdeo
  64350. smCharFISKana
  64351. smCharFISRussian
  64352. smCharLeft
  64353. smCharLower
  64354. smCharPortion
  64355. smCharPunct
  64356. smCharRight
  64357. smCharUpper
  64358. smChinese
  64359. smcReserved
  64360. smcReserved12
  64361. smcRightMask
  64362. smcTypeMask
  64363. smcUpperMask
  64364. smCyrillic
  64365. smDefault
  64366. smDevanagari
  64367. smDoubleByte
  64368. smEnabled
  64369. smfDualCaret
  64370. smFirstByte
  64371. smFISClassLvl0
  64372. smFISClassLvl1
  64373. smFISClassLvl2
  64374. smFISClassUser
  64375. smFondEnd
  64376. smFondStart
  64377. smFontForce
  64378. smForced
  64379. smfShowIcon
  64380. smGeez
  64381. smGenFlags
  64382. smGeorgian
  64383. smGreek
  64384. smGujarati
  64385. smGurmukhi
  64386. smHebrew
  64387. smHilite
  64388. smIntlForce
  64389. smJapanese
  64390. smKannada
  64391. smKCHRCache
  64392. smKeyCache
  64393. smKeyLastScript
  64394. smKeyNextKybd
  64395. smKeyNextScript
  64396. smKeyScript
  64397. smKeySwap
  64398. smKeySysScript
  64399. smKhmer
  64400. smKorean
  64401. smLaotian
  64402. smLastByte
  64403. smLastScript
  64404. smLeftCaret
  64405. smLeftStyleRun
  64406. smMalayalam
  64407. smMaldivian
  64408. smMaskAll
  64409. smMaskAscii
  64410. smMaskAscii1
  64411. smMaskAscii2
  64412. smMaskGana2
  64413. smMaskKana1
  64414. smMaskKana2
  64415. smMaskNative
  64416. smMiddleByte
  64417. smMiddleStyleRun
  64418. smMongolian
  64419. smMunged
  64420. smNotInstalled
  64421. smNotTruncated
  64422. smOnlyStyleRun
  64423. smOriya
  64424. smOverride
  64425. smPrint
  64426. smPunctBlank
  64427. smPunctNormal
  64428. smPunctNumber
  64429. smPunctSymbol
  64430. smRegionCode
  64431. smRightCaret
  64432. smRightStyleRun
  64433. smRoman
  64434. smRSymbol
  64435. smRussian
  64436. smScriptAppFond
  64437. smScriptAppFondSize
  64438. smScriptBundle
  64439. smScriptCreator
  64440. smScriptDate
  64441. smScriptEnabled
  64442. smScriptFile
  64443. smScriptFlags
  64444. smScriptHelpFondSize
  64445. smScriptIcon
  64446. smScriptJust
  64447. smScriptKeys
  64448. smScriptLang
  64449. smScriptMonoFondSize
  64450. smScriptMunged
  64451. smScriptName
  64452. smScriptNumber
  64453. smScriptNumDate
  64454. smScriptPrefFondSize
  64455. smScriptPrint
  64456. smScriptRedraw
  64457. smScriptRight
  64458. smScriptRsvd3
  64459. smScriptSmallFondSize
  64460. smScriptSort
  64461. smScriptSysFond
  64462. smScriptSysFondSize
  64463. smScriptToken
  64464. smScriptTrap
  64465. smScriptVersion
  64466. smsfAutoInit
  64467. smsfB0Digits
  64468. smsfContext
  64469. smsfForms
  64470. smsfIntellCP
  64471. smsfLigatures
  64472. smsfNatCase
  64473. smsfNoForceFont
  64474. smsfReverse
  64475. smsfSingByte
  64476. smSimpChinese
  64477. smSindhi
  64478. smSingleByte
  64479. smSinhalese
  64480. smSlavic
  64481. smSysRef
  64482. smSysScript
  64483. smTamil
  64484. smTelugu
  64485. smThai
  64486. smTibetan
  64487. smTradChinese
  64488. smTransAscii
  64489. smTransAscii1
  64490. smTransAscii2
  64491. smTransCase
  64492. smTransGana2
  64493. smTransKana1
  64494. smTransKana2
  64495. smTransLower
  64496. smTransNative
  64497. smTransSystem
  64498. smTransUpper
  64499. smTruncated
  64500. smTruncEnd
  64501. smTruncErr
  64502. smTruncMiddle
  64503. smUninterp
  64504. smUprHalfCharSet
  64505. smVersion
  64506. smVietnamese
  64507. stringOverflow
  64508. StyledLineBreakCode
  64509. tilde
  64510. togChar12HourBit
  64511. togCharZCycleBit
  64512. togDelta12HourBit
  64513. toggleBadChar
  64514. toggleBadDelta
  64515. toggleBadField
  64516. toggleBadNum
  64517. toggleErr3
  64518. toggleErr4
  64519. toggleErr5
  64520. toggleOK
  64521. toggleOutOfRange
  64522. TogglePB
  64523. ToggleResults
  64524. toggleUndefined
  64525. toggleUnknown
  64526. tokDecPoint
  64527. tokEMinus
  64528. token1Quote
  64529. token2Equal
  64530. token2Quote
  64531. tokenAlpha
  64532. tokenAltNum
  64533. tokenAltReal
  64534. tokenAmpersand
  64535. tokenAsterisk
  64536. tokenAtSign
  64537. tokenBackSlash
  64538. tokenBar
  64539. TokenBlock
  64540. TokenBlockPtr
  64541. tokenCapPi
  64542. tokenCarat
  64543. tokenColon
  64544. tokenColonEqual
  64545. tokenComma
  64546. tokenDivide
  64547. tokenDollar
  64548. tokenEmpty
  64549. tokenEqual
  64550. tokenErr
  64551. tokenEscape
  64552. tokenExclam
  64553. tokenExclamEqual
  64554. tokenFraction
  64555. tokenGreat
  64556. tokenGreatEqual1
  64557. tokenGreatEqual2
  64558. tokenHash
  64559. tokenInfinity
  64560. tokenIntegral
  64561. tokenIntl
  64562. tokenIntlCurrency
  64563. tokenLeft1Quote
  64564. tokenLeft2Quote
  64565. tokenLeftBracket
  64566. tokenLeftComment
  64567. tokenLeftCurly
  64568. tokenLeftEnclose
  64569. tokenLeftLit
  64570. tokenLeftParen
  64571. tokenLeftSingGuillemet
  64572. tokenLess
  64573. tokenLessEqual1
  64574. tokenLessEqual2
  64575. tokenLessGreat
  64576. tokenLiteral
  64577. tokenMicro
  64578. tokenMinus
  64579. tokenNewLine
  64580. tokenNil
  64581. tokenNoBreakSpace
  64582. tokenNotEqual
  64583. tokenNumeric
  64584. tokenOK
  64585. tokenOverflow
  64586. tokenPercent
  64587. tokenPeriod
  64588. tokenPerThousand
  64589. tokenPi
  64590. tokenPlus
  64591. tokenPlusMinus
  64592. tokenQuestion
  64593. tokenRealNum
  64594. TokenRec
  64595. TokenRecPtr
  64596. tokenReserve1
  64597. tokenReserve2
  64598. TokenResults
  64599. tokenRight1Quote
  64600. tokenRight2Quote
  64601. tokenRightBracket
  64602. tokenRightComment
  64603. tokenRightCurly
  64604. tokenRightEnclose
  64605. tokenRightLit
  64606. tokenRightParen
  64607. tokenRightSingGuillemet
  64608. tokenRoot
  64609. tokenSemicolon
  64610. tokenSigma
  64611. tokenSlash
  64612. tokenTilda
  64613. tokenUnderline
  64614. tokenUnknown
  64615. tokenWhite
  64616. tokEPlus
  64617. tokEscape
  64618. tokLeader
  64619. tokLeadPlacer
  64620. tokLeftQuote
  64621. tokMaxSymbols
  64622. tokMinusSign
  64623. tokNonLeader
  64624. tokPercent
  64625. tokPlusSign
  64626. tokRightQuote
  64627. tokSeparator
  64628. tokThousands
  64629. tokZeroLead
  64630. tooManySeps
  64631. TruncCode
  64632. UntokenTable
  64633. UntokenTableHandle
  64634. UntokenTablePtr
  64635. validDateFields
  64636. weekOfYearField
  64637. weekOfYearMask
  64638. WideChar
  64639. WideCharArr
  64640. yearField
  64641. yearMask
  64642.  
  64643. æKY smRoman
  64644. æFc Script.h
  64645. æT #define
  64646. æD 
  64647. /* Script Interface System Numbers */
  64648.  
  64649. #define smRoman 0 /*Font script is Roman.*/
  64650. æC 
  64651. _______________________________________________________________________________
  64652.  
  64653. »Determining the Script in Use
  64654.  
  64655. The characteristics of different scripts require that text manipulation functions be
  64656. handled according to the script in use.  Every script has a unique identification
  64657. number, as shown in the following list:
  64658.  
  64659.   Constant     Value  Script
  64660.  
  64661.   smRoman        0    Normal ASCII alphabet
  64662.   smKanji        1    Japanese
  64663.   smChinese      2    Chinese
  64664.   smKorean       3    Korean
  64665.   smArabic       4    Arabic
  64666.   smHebrew       5    Hebrew
  64667.   smGreek        6    Greek
  64668.   smRussian      7    Cyrillic
  64669.   smReserved1    8    Reserved
  64670.   smDevanagari   9    Devanagari
  64671.   smGurmukhi    10    Gurmukhi
  64672.   smGujarati    11    Gujarati
  64673.   smOriya       12    Oriya
  64674.   smBengali     13    Bengali
  64675.   smTamil       14    Tamil
  64676.   smTelugu      15    Telugu
  64677.   smKannada     16    Kannada
  64678.   smMalayalam   17    Malayalam
  64679.   smSinhalese   18    Sinhalese
  64680.   smBurmese     19    Burmese
  64681.   smKhmer       20    Cambodian
  64682.   smThai        21    Thai
  64683.   smLaotian     22    Laotian
  64684.   smGeorgian    23    Georgian
  64685.   smArmenian    24    Armenian
  64686.   smMaldivian   25    Maldivian
  64687.   smTibetan     26    Tibetan
  64688.   smMongolian   27    Mongolian
  64689.   smAmharic     28    Ethiopian
  64690.   smSlavic      29    Non-Cyrillic Slavic
  64691.   smVietnamese  30    Vietnamese
  64692.   smSindhi      31    Sindhi
  64693.   smUninterp    32    Uninterpreted symbols (such as MacPaint palette symbols)
  64694.  
  64695. The Script Manager looks for one of these values in the font field of the current
  64696. grafPort (thePort) to determine which script the application is using.  The script
  64697. specified by the font of thePort is referred to as the font script.  For example, if
  64698. thePort’s font is Geneva, the font script will be Roman.  If thePort’s font is Kyoto,
  64699. the font script will be Japanese.  If the mapping from font to script results in a
  64700. request for a Script Interface System that is not available, the font script defaults
  64701. to Roman.
  64702.  
  64703. Note: Be sure to set the font in the current grafPort correctly so the Script
  64704.       Manager will know what script it is working with. Otherwise the results
  64705.       it returns will be meaningless (for example, if a block of Arabic text
  64706.       is treated as if it were kanji).
  64707.  
  64708. The font script is not to be confused with the key script, which is maintained by the
  64709. system.  The key script value determines which keyboard layout and input method to
  64710. use, but has no effect on characters drawn on the screen or on the operations performed
  64711. by the Script Manager routines.  The key and font scripts are not always the same. 
  64712. For example, while an international word processing application is using the Arabic
  64713. Interface System for keyboard input, it may also be drawing kanji and Roman text on
  64714. the screen. For further information about keyboard characters translation, see the
  64715. System Resource File chapter.
  64716.  
  64717. æKY smJapanese
  64718. æFc Script.h
  64719. æT #define
  64720. æD #define smJapanese 1 /*Font script is Japanese.*/
  64721. æC 
  64722.  
  64723. æKY smChinese
  64724. æFc Script.h
  64725. æT #define
  64726. æD #define smChinese 2 /*(use smTradChinese or smSimpChinese)*/
  64727. æC 
  64728.  
  64729. æKY smTradChinese
  64730. æFc Script.h
  64731. æT #define
  64732. æD #define smTradChinese 2 /*Font script is Traditional Chinese.*/
  64733. æC 
  64734.  
  64735. æKY smKorean
  64736. æFc Script.h
  64737. æT #define
  64738. æD #define smKorean 3 /*Font script is Korean.*/
  64739. æC 
  64740.  
  64741. æKY smArabic
  64742. æFc Script.h
  64743. æT #define
  64744. æD #define smArabic 4 /*Font script is Arabic.*/
  64745. æC 
  64746.  
  64747. æKY smHebrew
  64748. æFc Script.h
  64749. æT #define
  64750. æD #define smHebrew 5 /*Font script is Hebrew.*/
  64751. æC 
  64752.  
  64753. æKY smGreek
  64754. æFc Script.h
  64755. æT #define
  64756. æD #define smGreek 6 /*Font script is Greek.*/
  64757. æC 
  64758.  
  64759. æKY smRussian
  64760. æFc Script.h
  64761. æT #define
  64762. æD #define smRussian 7 /*Font script is Russian.*/
  64763. æC 
  64764.  
  64765. æKY smCyrillic
  64766. æFc Script.h
  64767. æT #define
  64768. æD #define smCyrillic 7 /*Equivalent to Russian.*/
  64769. æC 
  64770.  
  64771. æKY smRSymbol
  64772. æFc Script.h
  64773. æT #define
  64774. æD #define smRSymbol 8 /*Font script is Right-left symbol.*/
  64775. æC 
  64776.  
  64777. æKY smDevanagari
  64778. æFc Script.h
  64779. æT #define
  64780. æD #define smDevanagari 9 /*Font script is Devanagari.*/
  64781. æC 
  64782.  
  64783. æKY smGurmukhi
  64784. æFc Script.h
  64785. æT #define
  64786. æD #define smGurmukhi 10 /*Font script is Gurmukhi.*/
  64787. æC 
  64788.  
  64789. æKY smGujarati
  64790. æFc Script.h
  64791. æT #define
  64792. æD #define smGujarati 11 /*Font script is Gujarati.*/
  64793. æC 
  64794.  
  64795. æKY smOriya
  64796. æFc Script.h
  64797. æT #define
  64798. æD #define smOriya 12 /*Font script is Oriya.*/
  64799. æC 
  64800.  
  64801. æKY smBengali
  64802. æFc Script.h
  64803. æT #define
  64804. æD #define smBengali 13 /*Font script is Bengali.*/
  64805. æC 
  64806.  
  64807. æKY smTamil
  64808. æFc Script.h
  64809. æT #define
  64810. æD #define smTamil 14 /*Font script is Tamil.*/
  64811. æC 
  64812.  
  64813. æKY smTelugu
  64814. æFc Script.h
  64815. æT #define
  64816. æD #define smTelugu 15 /*Font script is Telugu.*/
  64817. æC 
  64818.  
  64819. æKY smKannada
  64820. æFc Script.h
  64821. æT #define
  64822. æD #define smKannada 16 /*Font script is Kannada.*/
  64823. æC 
  64824.  
  64825. æKY smMalayalam
  64826. æFc Script.h
  64827. æT #define
  64828. æD #define smMalayalam 17 /*Font script is Malayalam.*/
  64829. æC 
  64830.  
  64831. æKY smSinhalese
  64832. æFc Script.h
  64833. æT #define
  64834. æD #define smSinhalese 18 /*Font script is Sinhalese.*/
  64835. æC 
  64836.  
  64837. æKY smBurmese
  64838. æFc Script.h
  64839. æT #define
  64840. æD #define smBurmese 19 /*Font script is Burmese.*/
  64841. æC 
  64842. _______________________________________________________________________________
  64843.  
  64844. »Determining the Script in Use
  64845.  
  64846. The characteristics of different scripts require that text manipulation functions be
  64847. handled according to the script in use.  Every script has a unique identification
  64848. number, as shown in the following list:
  64849.  
  64850.   Constant     Value  Script
  64851.  
  64852.   smRoman        0    Normal ASCII alphabet
  64853.   smKanji        1    Japanese
  64854.   smChinese      2    Chinese
  64855.   smKorean       3    Korean
  64856.   smArabic       4    Arabic
  64857.   smHebrew       5    Hebrew
  64858.   smGreek        6    Greek
  64859.   smRussian      7    Cyrillic
  64860.   smReserved1    8    Reserved
  64861.   smDevanagari   9    Devanagari
  64862.   smGurmukhi    10    Gurmukhi
  64863.   smGujarati    11    Gujarati
  64864.   smOriya       12    Oriya
  64865.   smBengali     13    Bengali
  64866.   smTamil       14    Tamil
  64867.   smTelugu      15    Telugu
  64868.   smKannada     16    Kannada
  64869.   smMalayalam   17    Malayalam
  64870.   smSinhalese   18    Sinhalese
  64871.   smBurmese     19    Burmese
  64872.   smKhmer       20    Cambodian
  64873.   smThai        21    Thai
  64874.   smLaotian     22    Laotian
  64875.   smGeorgian    23    Georgian
  64876.   smArmenian    24    Armenian
  64877.   smMaldivian   25    Maldivian
  64878.   smTibetan     26    Tibetan
  64879.   smMongolian   27    Mongolian
  64880.   smAmharic     28    Ethiopian
  64881.   smSlavic      29    Non-Cyrillic Slavic
  64882.   smVietnamese  30    Vietnamese
  64883.   smSindhi      31    Sindhi
  64884.   smUninterp    32    Uninterpreted symbols (such as MacPaint palette symbols)
  64885.  
  64886. The Script Manager looks for one of these values in the font field of the current
  64887. grafPort (thePort) to determine which script the application is using.  The script
  64888. specified by the font of thePort is referred to as the font script.  For example, if
  64889. thePort’s font is Geneva, the font script will be Roman.  If thePort’s font is Kyoto,
  64890. the font script will be Japanese.  If the mapping from font to script results in a
  64891. request for a Script Interface System that is not available, the font script defaults
  64892. to Roman.
  64893.  
  64894. Note: Be sure to set the font in the current grafPort correctly so the Script
  64895.       Manager will know what script it is working with. Otherwise the results
  64896.       it returns will be meaningless (for example, if a block of Arabic text
  64897.       is treated as if it were kanji).
  64898.  
  64899. The font script is not to be confused with the key script, which is maintained by the
  64900. system.  The key script value determines which keyboard layout and input method to
  64901. use, but has no effect on characters drawn on the screen or on the operations performed
  64902. by the Script Manager routines.  The key and font scripts are not always the same. 
  64903. For example, while an international word processing application is using the Arabic
  64904. Interface System for keyboard input, it may also be drawing kanji and Roman text on
  64905. the screen. For further information about keyboard characters translation, see the
  64906. System Resource File chapter.
  64907.  
  64908. æKY smKhmer
  64909. æFc Script.h
  64910. æT #define
  64911. æD #define smKhmer 20 /*Font script is Khmer.*/
  64912. æC 
  64913.  
  64914. æKY smThai
  64915. æFc Script.h
  64916. æT #define
  64917. æD #define smThai 21 /*Font script is Thai.*/
  64918. æC 
  64919.  
  64920. æKY smLaotian
  64921. æFc Script.h
  64922. æT #define
  64923. æD #define smLaotian 22 /*Font script is Laotian.*/
  64924. æC 
  64925.  
  64926. æKY smGeorgian
  64927. æFc Script.h
  64928. æT #define
  64929. æD #define smGeorgian 23 /*Font script is Georgian.*/
  64930. æC 
  64931.  
  64932. æKY smArmenian
  64933. æFc Script.h
  64934. æT #define
  64935. æD #define smArmenian 24 /*Font script is Armenian.*/
  64936. æC 
  64937.  
  64938. æKY smMaldivian
  64939. æFc Script.h
  64940. æT #define
  64941. æD #define smMaldivian 25 /*(no more smMaldivian!)*/
  64942. æC 
  64943.  
  64944. æKY smSimpChinese
  64945. æFc Script.h
  64946. æT #define
  64947. æD #define smSimpChinese 25 /*Font script is Simplified Chinese.*/
  64948. æC 
  64949.  
  64950. æKY smTibetan
  64951. æFc Script.h
  64952. æT #define
  64953. æD #define smTibetan 26 /*Font script is Tibetan.*/
  64954. æC 
  64955.  
  64956. æKY smMongolian
  64957. æFc Script.h
  64958. æT #define
  64959. æD #define smMongolian 27 /*Font script is Mongolian.*/
  64960. æC 
  64961.  
  64962. æKY smAmharic
  64963. æFc Script.h
  64964. æT #define
  64965. æD #define smAmharic 28 /*old name for smGeez.*/
  64966. æC 
  64967.  
  64968. æKY smGeez
  64969. æFc Script.h
  64970. æT #define
  64971. æD #define smGeez 28 /*Font script is Geez (Ethiopic).*/
  64972. æC 
  64973.  
  64974. æKY smSlavic
  64975. æFc Script.h
  64976. æT #define
  64977. æD #define smSlavic 29 /*Font script is Slavic.*/
  64978. æC 
  64979.  
  64980. æKY smVietnamese
  64981. æFc Script.h
  64982. æT #define
  64983. æD #define smVietnamese 30 /*Font script is Vietnamese.*/
  64984. æC 
  64985.  
  64986. æKY smSindhi
  64987. æFc Script.h
  64988. æT #define
  64989. æD #define smSindhi 31 /*Font script is Sindhi.*/
  64990. æC 
  64991.  
  64992. æKY smUninterp
  64993. æFc Script.h
  64994. æT #define
  64995. æD #define smUninterp 32 /*Font script is uninterpreted symbols.*/
  64996. æC 
  64997.  
  64998. æKY langEnglish
  64999. æFc Script.h
  65000. æT #define
  65001. æD 
  65002. /* Language Codes */
  65003.  
  65004. #define langEnglish 0
  65005. æC 
  65006.  
  65007. æKY langFrench
  65008. æFc Script.h
  65009. æT #define
  65010. æD #define langFrench 1
  65011. æC 
  65012.  
  65013. æKY langGerman
  65014. æFc Script.h
  65015. æT #define
  65016. æD #define langGerman 2
  65017. æC 
  65018.  
  65019. æKY langItalian
  65020. æFc Script.h
  65021. æT #define
  65022. æD #define langItalian 3
  65023. æC 
  65024.  
  65025. æKY langDutch
  65026. æFc Script.h
  65027. æT #define
  65028. æD #define langDutch 4
  65029. æC 
  65030.  
  65031. æKY langSwedish
  65032. æFc Script.h
  65033. æT #define
  65034. æD #define langSwedish 5
  65035. æC 
  65036.  
  65037. æKY langSpanish
  65038. æFc Script.h
  65039. æT #define
  65040. æD #define langSpanish 6
  65041. æC 
  65042.  
  65043. æKY langDanish
  65044. æFc Script.h
  65045. æT #define
  65046. æD #define langDanish 7
  65047. æC 
  65048.  
  65049. æKY langPortugese
  65050. æFc Script.h
  65051. æT #define
  65052. æD #define langPortugese 8
  65053. æC 
  65054.  
  65055. æKY langPortuguese
  65056. æFc Script.h
  65057. æT #define
  65058. æD #define langPortuguese 8
  65059. æC 
  65060.  
  65061. æKY langNorwegian
  65062. æFc Script.h
  65063. æT #define
  65064. æD #define langNorwegian 9
  65065. æC 
  65066.  
  65067. æKY langHebrew
  65068. æFc Script.h
  65069. æT #define
  65070. æD #define langHebrew 10
  65071. æC 
  65072.  
  65073. æKY langJapanese
  65074. æFc Script.h
  65075. æT #define
  65076. æD #define langJapanese 11
  65077. æC 
  65078.  
  65079. æKY langArabic
  65080. æFc Script.h
  65081. æT #define
  65082. æD #define langArabic 12
  65083. æC 
  65084.  
  65085. æKY langFinnish
  65086. æFc Script.h
  65087. æT #define
  65088. æD #define langFinnish 13
  65089. æC 
  65090.  
  65091. æKY langGreek
  65092. æFc Script.h
  65093. æT #define
  65094. æD #define langGreek 14
  65095. æC 
  65096.  
  65097. æKY langIcelandic
  65098. æFc Script.h
  65099. æT #define
  65100. æD #define langIcelandic 15
  65101. æC 
  65102.  
  65103. æKY langMalta
  65104. æFc Script.h
  65105. æT #define
  65106. æD #define langMalta 16
  65107. æC 
  65108.  
  65109. æKY langMaltese
  65110. æFc Script.h
  65111. æT #define
  65112. æD #define langMaltese 16
  65113. æC 
  65114.  
  65115. æKY langTurkish
  65116. æFc Script.h
  65117. æT #define
  65118. æD #define langTurkish 17
  65119. æC 
  65120.  
  65121. æKY langYugoslavian
  65122. æFc Script.h
  65123. æT #define
  65124. æD #define langYugoslavian 18
  65125. æC 
  65126.  
  65127. æKY langChinese
  65128. æFc Script.h
  65129. æT #define
  65130. æD #define langChinese 19 /* (use langTradChinese or langSimpChinese) */
  65131. æC 
  65132.  
  65133. æKY langTradChinese
  65134. æFc Script.h
  65135. æT #define
  65136. æD #define langTradChinese 19 /* Chinese in traditional characters */
  65137. æC 
  65138.  
  65139. æKY langUrdu
  65140. æFc Script.h
  65141. æT #define
  65142. æD #define langUrdu 20
  65143. æC 
  65144.  
  65145. æKY langHindi
  65146. æFc Script.h
  65147. æT #define
  65148. æD #define langHindi 21
  65149. æC 
  65150.  
  65151. æKY langThai
  65152. æFc Script.h
  65153. æT #define
  65154. æD #define langThai 22
  65155. æC 
  65156.  
  65157. æKY langKorean
  65158. æFc Script.h
  65159. æT #define
  65160. æD #define langKorean 23
  65161. æC 
  65162.  
  65163. æKY langLithuanian
  65164. æFc Script.h
  65165. æT #define
  65166. æD #define langLithuanian 24
  65167. æC 
  65168.  
  65169. æKY langPolish
  65170. æFc Script.h
  65171. æT #define
  65172. æD #define langPolish 25
  65173. æC 
  65174.  
  65175. æKY langHungarian
  65176. æFc Script.h
  65177. æT #define
  65178. æD #define langHungarian 26
  65179. æC 
  65180.  
  65181. æKY langEstonian
  65182. æFc Script.h
  65183. æT #define
  65184. æD #define langEstonian 27
  65185. æC 
  65186.  
  65187. æKY langLettish
  65188. æFc Script.h
  65189. æT #define
  65190. æD #define langLettish 28
  65191. æC 
  65192.  
  65193. æKY langLapponian
  65194. æFc Script.h
  65195. æT #define
  65196. æD #define langLapponian 29
  65197. æC 
  65198.  
  65199. æKY langFaeroese
  65200. æFc Script.h
  65201. æT #define
  65202. æD #define langFaeroese 30
  65203. æC 
  65204.  
  65205. æKY langFarsi
  65206. æFc Script.h
  65207. æT #define
  65208. æD #define langFarsi 31
  65209. æC 
  65210.  
  65211. æKY langRussian
  65212. æFc Script.h
  65213. æT #define
  65214. æD #define langRussian 32
  65215. æC 
  65216.  
  65217. æKY langSimpChinese
  65218. æFc Script.h
  65219. æT #define
  65220. æD #define langSimpChinese 33 /* Chinese in simplified characters */
  65221. æC 
  65222.  
  65223. æKY calGregorian
  65224. æFc Script.h
  65225. æT #define
  65226. æD 
  65227. /* Calendar Codes */
  65228.  
  65229. #define calGregorian 0
  65230. æC 
  65231.  
  65232. æKY calArabicCivil
  65233. æFc Script.h
  65234. æT #define
  65235. æD #define calArabicCivil 1
  65236. æC 
  65237.  
  65238. æKY calArabicLunar
  65239. æFc Script.h
  65240. æT #define
  65241. æD #define calArabicLunar 2
  65242. æC 
  65243.  
  65244. æKY calJapanese
  65245. æFc Script.h
  65246. æT #define
  65247. æD #define calJapanese 3
  65248. æC 
  65249.  
  65250. æKY calJewish
  65251. æFc Script.h
  65252. æT #define
  65253. æD #define calJewish 4
  65254. æC 
  65255.  
  65256. æKY calCoptic
  65257. æFc Script.h
  65258. æT #define
  65259. æD #define calCoptic 5
  65260. æC 
  65261.  
  65262. æKY intWestern
  65263. æFc Script.h
  65264. æT #define
  65265. æD 
  65266. /* Integer Format Codes */
  65267.  
  65268. #define intWestern 0
  65269. æC 
  65270.  
  65271. æKY intArabic
  65272. æFc Script.h
  65273. æT #define
  65274. æD #define intArabic 1
  65275. æC 
  65276.  
  65277. æKY intRoman
  65278. æFc Script.h
  65279. æT #define
  65280. æD #define intRoman 2
  65281. æC 
  65282.  
  65283. æKY intJapanese
  65284. æFc Script.h
  65285. æT #define
  65286. æD #define intJapanese 3
  65287. æC 
  65288.  
  65289. æKY intEuropean
  65290. æFc Script.h
  65291. æT #define
  65292. æD #define intEuropean 4
  65293. æC 
  65294.  
  65295. æKY intOutputMask
  65296. æFc Script.h
  65297. æT #define
  65298. æD #define intOutputMask 0x8000
  65299. æC 
  65300.  
  65301. æKY smSingleByte
  65302. æFc Script.h
  65303. æT #define
  65304. æD 
  65305. /* CharByte byte types */
  65306.  
  65307. #define smSingleByte 0
  65308. æC 
  65309.  
  65310. æKY smFirstByte
  65311. æFc Script.h
  65312. æT #define
  65313. æD #define smFirstByte -1
  65314. æC 
  65315.  
  65316. æKY smLastByte
  65317. æFc Script.h
  65318. æT #define
  65319. æD #define smLastByte 1
  65320. æC 
  65321.  
  65322. æKY smMiddleByte
  65323. æFc Script.h
  65324. æT #define
  65325. æD #define smMiddleByte 2
  65326. æC 
  65327.  
  65328. æKY smcTypeMask
  65329. æFc Script.h
  65330. æT #define
  65331. æD 
  65332. /* CharType field masks */
  65333.  
  65334. #define smcTypeMask 0x000F
  65335. æC 
  65336.  
  65337. æKY smcReserved
  65338. æFc Script.h
  65339. æT #define
  65340. æD #define smcReserved 0x00F0
  65341. æC 
  65342.  
  65343. æKY smcClassMask
  65344. æFc Script.h
  65345. æT #define
  65346. æD #define smcClassMask 0x0F00
  65347. æC 
  65348.  
  65349. æKY smcReserved12
  65350. æFc Script.h
  65351. æT #define
  65352. æD #define smcReserved12 0x1000
  65353. æC 
  65354.  
  65355. æKY smcRightMask
  65356. æFc Script.h
  65357. æT #define
  65358. æD #define smcRightMask 0x2000
  65359. æC 
  65360.  
  65361. æKY smcUpperMask
  65362. æFc Script.h
  65363. æT #define
  65364. æD #define smcUpperMask 0x4000
  65365. æC 
  65366.  
  65367. æKY smcDoubleMask
  65368. æFc Script.h
  65369. æT #define
  65370. æD #define smcDoubleMask 0x8000
  65371. æC 
  65372.  
  65373. æKY smCharPunct
  65374. æFc Script.h
  65375. æT #define
  65376. æD 
  65377. /* CharType character types */
  65378.  
  65379. #define smCharPunct 0
  65380. æC 
  65381.  
  65382. æKY smCharAscii
  65383. æFc Script.h
  65384. æT #define
  65385. æD #define smCharAscii 1
  65386. æC 
  65387.  
  65388. æKY smCharEuro
  65389. æFc Script.h
  65390. æT #define
  65391. æD #define smCharEuro 7
  65392. æC 
  65393.  
  65394. æKY smCharFISKana
  65395. æFc Script.h
  65396. æT #define
  65397. æD 
  65398. /* additional CharType character types for FIS character sets */
  65399.  
  65400. #define smCharFISKana 2 /*Katakana*/
  65401. æC 
  65402.  
  65403. æKY smCharFISGana
  65404. æFc Script.h
  65405. æT #define
  65406. æD #define smCharFISGana 3 /*Hiragana*/
  65407. æC 
  65408.  
  65409. æKY smCharFISIdeo
  65410. æFc Script.h
  65411. æT #define
  65412. æD #define smCharFISIdeo 4 /*Hanzi, Kanji, Hanja*/
  65413. æC 
  65414.  
  65415. æKY smCharFISGreek
  65416. æFc Script.h
  65417. æT #define
  65418. æD #define smCharFISGreek 5 /*Greek (2-byte)*/
  65419. æC 
  65420.  
  65421. æKY smCharFISRussian
  65422. æFc Script.h
  65423. æT #define
  65424. æD #define smCharFISRussian 6 /*Russian/Cyrillic (2-byte)*/
  65425. æC 
  65426.  
  65427. æKY smCharFISHangul
  65428. æFc Script.h
  65429. æT #define
  65430. æD #define smCharFISHangul 8 /*Hangul (**tentative**)*/
  65431. æC 
  65432.  
  65433. æKY smPunctNormal
  65434. æFc Script.h
  65435. æT #define
  65436. æD 
  65437. /* CharType classes (smCharPunct sub-types) */
  65438.  
  65439. #define smPunctNormal 0x0000
  65440. æC 
  65441.  
  65442. æKY smPunctNumber
  65443. æFc Script.h
  65444. æT #define
  65445. æD #define smPunctNumber 0x0100
  65446. æC 
  65447.  
  65448. æKY smPunctSymbol
  65449. æFc Script.h
  65450. æT #define
  65451. æD #define smPunctSymbol 0x0200
  65452. æC 
  65453.  
  65454. æKY smPunctBlank
  65455. æFc Script.h
  65456. æT #define
  65457. æD #define smPunctBlank 0x0300
  65458. æC 
  65459.  
  65460. æKY smFISClassLvl0
  65461. æFc Script.h
  65462. æT #define
  65463. æD 
  65464. /* additional CharType classes for FIS (smCharFISIdeo sub-types) */
  65465.  
  65466. #define smFISClassLvl0 0x0000 /*level 0 char*/
  65467. æC 
  65468.  
  65469. æKY smFISClassLvl1
  65470. æFc Script.h
  65471. æT #define
  65472. æD #define smFISClassLvl1 0x0100 /*level 1 char*/
  65473. æC 
  65474.  
  65475. æKY smFISClassLvl2
  65476. æFc Script.h
  65477. æT #define
  65478. æD #define smFISClassLvl2 0x0200 /*level 2 char*/
  65479. æC 
  65480.  
  65481. æKY smFISClassUser
  65482. æFc Script.h
  65483. æT #define
  65484. æD #define smFISClassUser 768 /*user char*/
  65485. æC 
  65486.  
  65487. æKY smCharLeft
  65488. æFc Script.h
  65489. æT #define
  65490. æD 
  65491. /* CharType directions */
  65492.  
  65493. #define smCharLeft 0x0000
  65494. æC 
  65495.  
  65496. æKY smCharRight
  65497. æFc Script.h
  65498. æT #define
  65499. æD #define smCharRight 0x2000
  65500. æC 
  65501.  
  65502. æKY smCharLower
  65503. æFc Script.h
  65504. æT #define
  65505. æD 
  65506. /* CharType case modifers */
  65507.  
  65508. #define smCharLower 0x0000
  65509. æC 
  65510.  
  65511. æKY smCharUpper
  65512. æFc Script.h
  65513. æT #define
  65514. æD #define smCharUpper 0x4000
  65515. æC 
  65516.  
  65517. æKY smChar1byte
  65518. æFc Script.h
  65519. æT #define
  65520. æD 
  65521. /* CharType character size modifiers (1 or multiple bytes). */
  65522.  
  65523. #define smChar1byte 0x0000
  65524. æC 
  65525.  
  65526. æKY smChar2byte
  65527. æFc Script.h
  65528. æT #define
  65529. æD #define smChar2byte 0x8000
  65530. æC 
  65531.  
  65532. æKY smLeftCaret
  65533. æFc Script.h
  65534. æT #define
  65535. æD 
  65536. /* Char2Pixel directions */
  65537.  
  65538. #define smLeftCaret 0 /*Place caret for left block.*/
  65539. æC 
  65540.  
  65541. æKY smRightCaret
  65542. æFc Script.h
  65543. æT #define
  65544. æD #define smRightCaret -1 /*Place caret for right block.*/
  65545. æC 
  65546.  
  65547. æKY smHilite
  65548. æFc Script.h
  65549. æT #define
  65550. æD #define smHilite 1 /*Direction is TESysJust.*/
  65551. æC 
  65552.  
  65553. æKY smTransAscii
  65554. æFc Script.h
  65555. æT #define
  65556. æD 
  65557. /* Transliterate target types */
  65558.  
  65559. #define smTransAscii 0
  65560. æC 
  65561.  
  65562. æKY smTransNative
  65563. æFc Script.h
  65564. æT #define
  65565. æD #define smTransNative 1
  65566. æC 
  65567.  
  65568. æKY smTransCase
  65569. æFc Script.h
  65570. æT #define
  65571. æD #define smTransCase 0xFE
  65572. æC 
  65573.  
  65574. æKY smTransSystem
  65575. æFc Script.h
  65576. æT #define
  65577. æD #define smTransSystem 0xFF /*convert to system script*/
  65578. æC 
  65579.  
  65580. æKY smTransAscii1
  65581. æFc Script.h
  65582. æT #define
  65583. æD 
  65584. /* Transliterate target types for FIS */
  65585.  
  65586. #define smTransAscii1 2 /*1-byte Roman*/
  65587. æC 
  65588.  
  65589. æKY smTransAscii2
  65590. æFc Script.h
  65591. æT #define
  65592. æD #define smTransAscii2 3 /*2-byte Roman*/
  65593. æC 
  65594.  
  65595. æKY smTransKana1
  65596. æFc Script.h
  65597. æT #define
  65598. æD #define smTransKana1 4 /*1-byte Katakana*/
  65599. æC 
  65600.  
  65601. æKY smTransKana2
  65602. æFc Script.h
  65603. æT #define
  65604. æD #define smTransKana2 5 /*2-byte Katakana*/
  65605. æC 
  65606.  
  65607. æKY smTransGana2
  65608. æFc Script.h
  65609. æT #define
  65610. æD #define smTransGana2 7 /*2-byte Hiragana (no 1-byte Hiragana)*/
  65611. æC 
  65612.  
  65613. æKY smTransLower
  65614. æFc Script.h
  65615. æT #define
  65616. æD 
  65617. /* Transliterate target modifiers */
  65618.  
  65619. #define smTransLower 0x4000
  65620. æC 
  65621.  
  65622. æKY smTransUpper
  65623. æFc Script.h
  65624. æT #define
  65625. æD #define smTransUpper 0x8000
  65626. æC 
  65627.  
  65628. æKY smMaskAll
  65629. æFc Script.h
  65630. æT #define
  65631. æD 
  65632. /* Transliterate source mask - general */
  65633.  
  65634. #define smMaskAll 0xFFFFFFFF /*Convert all text*/
  65635. æC 
  65636.  
  65637. æKY smMaskAscii
  65638. æFc Script.h
  65639. æT #define
  65640. æD 
  65641. /* Transliterate source masks */
  65642.  
  65643. #define smMaskAscii 0x00000001 /*2^smTransAscii*/
  65644. æC 
  65645.  
  65646. æKY smMaskNative
  65647. æFc Script.h
  65648. æT #define
  65649. æD #define smMaskNative 0x00000002 /*2^smTransNative*/
  65650. æC 
  65651.  
  65652. æKY smMaskAscii1
  65653. æFc Script.h
  65654. æT #define
  65655. æD 
  65656. /* Transliterate source masks for FIS */
  65657.  
  65658. #define smMaskAscii1 0x00000004 /*2^smTransAscii1*/
  65659. æC 
  65660.  
  65661. æKY smMaskAscii2
  65662. æFc Script.h
  65663. æT #define
  65664. æD #define smMaskAscii2 0x00000008 /*2^smTransAscii2*/
  65665. æC 
  65666.  
  65667. æKY smMaskKana1
  65668. æFc Script.h
  65669. æT #define
  65670. æD #define smMaskKana1 0x00000010 /*2^smTransKana1*/
  65671. æC 
  65672.  
  65673. æKY smMaskKana2
  65674. æFc Script.h
  65675. æT #define
  65676. æD #define smMaskKana2 0x00000020 /*2^smTransKana2*/
  65677. æC 
  65678.  
  65679. æKY smMaskGana2
  65680. æFc Script.h
  65681. æT #define
  65682. æD #define smMaskGana2 0x00000080 /*2^smTransGana2*/
  65683. æC 
  65684.  
  65685. æKY smNotInstalled
  65686. æFc Script.h
  65687. æT #define
  65688. æD 
  65689. /* Result values from GetEnvirons, SetEnvirons, GetScript and SetScript calls. */
  65690.  
  65691. #define smNotInstalled 0 /*routine not available in script*/
  65692. æC 
  65693.  
  65694. æKY smBadVerb
  65695. æFc Script.h
  65696. æT #define
  65697. æD #define smBadVerb -1 /*Bad verb passed to a routine.*/
  65698. æC 
  65699.  
  65700. æKY smBadScript
  65701. æFc Script.h
  65702. æT #define
  65703. æD #define smBadScript -2 /*Bad script code passed to a routine.*/
  65704. æC 
  65705.  
  65706. æKY smVersion
  65707. æFc Script.h
  65708. æT #define
  65709. æD 
  65710. /* GetEnvirons and SetEnvirons verbs */
  65711.  
  65712. #define smVersion 0 /*Environment version number.*/
  65713. æC 
  65714.   /* GetEnvirons verbs */
  65715.  
  65716.   smVersion      0        Environment version
  65717.   smMunged       2        Globals changed count
  65718.   smEnabled      4        Environment enabled flag
  65719.   smBiDirect     6        Set if scripts of different directions
  65720.                           are installed together
  65721.   smFontForce    8        Force font flag
  65722.   smIntlForce    10       Force international utilities flag
  65723.   smForced       12       Current script forced to system script
  65724.   smDefault      14       Current script defaulted to Roman script
  65725.   smPrint        16       Printer action routine
  65726.   smSysScript    18       System script
  65727.   smLastScript   20       Last keyboard script
  65728.   smKeyScript    22       Keyboard script
  65729.   smSysRef       24       System folder reference number
  65730.   smKeyCache     26       Keyboard table cache pointer
  65731.   smKeySwap      28       Swapping table pointer
  65732.   smGenFlags     30       General Flags
  65733.   smOverride     32       Script Override flags
  65734.   smCharPortion  34       Ch vs Sp Extra proportion, 4.12 fixed
  65735.  
  65736. æKY smMunged
  65737. æFc Script.h
  65738. æT #define
  65739. æD #define smMunged 2 /*Globals change count.*/
  65740. æC 
  65741.  
  65742. æKY smEnabled
  65743. æFc Script.h
  65744. æT #define
  65745. æD #define smEnabled 4 /*Environment enabled flag.*/
  65746. æC 
  65747.  
  65748. æKY smBidirect
  65749. æFc Script.h
  65750. æT #define
  65751. æD #define smBidirect 6 /*At least on bidirect script.*/
  65752. æC 
  65753.  
  65754. æKY smFontForce
  65755. æFc Script.h
  65756. æT #define
  65757. æD #define smFontForce 8 /*Force font flag.*/
  65758. æC 
  65759.  
  65760. æKY smIntlForce
  65761. æFc Script.h
  65762. æT #define
  65763. æD #define smIntlForce 10 /*Force intl flag.*/
  65764. æC 
  65765.  
  65766. æKY smForced
  65767. æFc Script.h
  65768. æT #define
  65769. æD #define smForced 12 /*script forced to system script.*/
  65770. æC 
  65771.  
  65772. æKY smDefault
  65773. æFc Script.h
  65774. æT #define
  65775. æD #define smDefault 14 /*script defaulted to Roman script.*/
  65776. æC 
  65777.  
  65778. æKY smPrint
  65779. æFc Script.h
  65780. æT #define
  65781. æD #define smPrint 16 /*Printer action routine.*/
  65782. æC 
  65783.  
  65784. æKY smSysScript
  65785. æFc Script.h
  65786. æT #define
  65787. æD #define smSysScript 18 /*System script.*/
  65788. æC 
  65789.  
  65790. æKY smLastScript
  65791. æFc Script.h
  65792. æT #define
  65793. æD #define smLastScript 20 /*Last keyboard script.*/
  65794. æC 
  65795.  
  65796. æKY smKeyScript
  65797. æFc Script.h
  65798. æT #define
  65799. æD #define smKeyScript 22 /*Keyboard script.*/
  65800. æC 
  65801.  
  65802. æKY smSysRef
  65803. æFc Script.h
  65804. æT #define
  65805. æD #define smSysRef 24 /*System folder refNum.*/
  65806. æC 
  65807.  
  65808. æKY smKeyCache
  65809. æFc Script.h
  65810. æT #define
  65811. æD #define smKeyCache 26 /*Keyboard table cache pointer.*/
  65812. æC 
  65813.  
  65814. æKY smKeySwap
  65815. æFc Script.h
  65816. æT #define
  65817. æD #define smKeySwap 28 /*Swapping table pointer.*/
  65818. æC 
  65819.  
  65820. æKY smGenFlags
  65821. æFc Script.h
  65822. æT #define
  65823. æD #define smGenFlags 30 /*General flags long*/
  65824. æC 
  65825.  
  65826. æKY smOverride
  65827. æFc Script.h
  65828. æT #define
  65829. æD #define smOverride 32 /*Script override flags.*/
  65830. æC 
  65831.  
  65832. æKY smCharPortion
  65833. æFc Script.h
  65834. æT #define
  65835. æD #define smCharPortion 34 /*Ch vs SpExtra proportion*/
  65836. æC 
  65837.  
  65838. æKY smDoubleByte
  65839. æFc Script.h
  65840. æT #define
  65841. æD 
  65842. /*  New for System 7.0:  */
  65843.  
  65844. #define smDoubleByte 36 /*Flag for double-byte script installed*/
  65845. æC 
  65846.  
  65847. æKY smKCHRCache
  65848. æFc Script.h
  65849. æT #define
  65850. æD #define smKCHRCache 38 /*Returns pointer to KCHR cache*/
  65851. æC 
  65852.  
  65853. æKY smRegionCode
  65854. æFc Script.h
  65855. æT #define
  65856. æD #define smRegionCode 40 /*Returns current region code (verXxx)*/
  65857. æC 
  65858.  
  65859. æKY smScriptVersion
  65860. æFc Script.h
  65861. æT #define
  65862. æD 
  65863. /* GetScript and SetScript verbs.
  65864. Note: Verbs private to script systems are negative, while
  65865. those general across script systems are non-negative. */
  65866.  
  65867. #define smScriptVersion 0 /*Script software version.*/
  65868. æC 
  65869.   /* GetScript verbs */
  65870.  
  65871.   smScriptVersion    0        Software version
  65872.   smScriptMunged     2        Script entry changed count
  65873.   smScriptEnabled    4        Script enabled flag
  65874.   smScriptRight      6        Right-to-left flag
  65875.   smScriptJust       8        Justification flag
  65876.   smScriptRedraw     10       Word redraw flag
  65877.   smScriptSysFond    12       Preferred system font
  65878.   smScriptAppFond    14       Preferred application font
  65879.   smScriptNumber     16       Script 'itl0' ID, from dictionary
  65880.   smScriptDate       18       Script 'itl1' ID, from dictionary
  65881.   smScriptSort       20       Script 'itl2' ID, from dictionary
  65882.   smScriptFlags      22       Script Flags Word
  65883.   smScriptToken      24       'itl4' ID number
  65884.   smScriptRsvd3      26       Reserved
  65885.   smScriptLang       28       Script’s language code
  65886.   smScriptNumDate    30       Number/Date Representation codes
  65887.   smScriptKeys       32       Script 'KCHR' ID, from dictionary
  65888.   smScriptIcon       34       Script 'SICN' ID, from dictionary
  65889.   smScriptPrint      36       Script printer action routine
  65890.   smScriptTrap       38       Trap entry pointer
  65891.   smScriptCreator    40       Script file creator
  65892.   smScriptFile       42       Script file name
  65893.   smScriptName       44       Script name
  65894.  
  65895. æKY smScriptMunged
  65896. æFc Script.h
  65897. æT #define
  65898. æD #define smScriptMunged 2 /*Script entry changed count.*/
  65899. æC 
  65900.  
  65901. æKY smScriptEnabled
  65902. æFc Script.h
  65903. æT #define
  65904. æD #define smScriptEnabled 4 /*Script enabled flag.*/
  65905. æC 
  65906.  
  65907. æKY smScriptRight
  65908. æFc Script.h
  65909. æT #define
  65910. æD #define smScriptRight 6 /*Right to left flag.*/
  65911. æC 
  65912.  
  65913. æKY smScriptJust
  65914. æFc Script.h
  65915. æT #define
  65916. æD #define smScriptJust 8 /*Justification flag.*/
  65917. æC 
  65918.  
  65919. æKY smScriptRedraw
  65920. æFc Script.h
  65921. æT #define
  65922. æD #define smScriptRedraw 10 /*Word redraw flag.*/
  65923. æC 
  65924.  
  65925. æKY smScriptSysFond
  65926. æFc Script.h
  65927. æT #define
  65928. æD #define smScriptSysFond 12 /*Preferred system font.*/
  65929. æC 
  65930.  
  65931. æKY smScriptAppFond
  65932. æFc Script.h
  65933. æT #define
  65934. æD #define smScriptAppFond 14 /*Preferred Application font.*/
  65935. æC 
  65936.  
  65937. æKY smScriptBundle
  65938. æFc Script.h
  65939. æT #define
  65940. æD #define smScriptBundle 16 /*Beginning of dictionary verbs.*/
  65941. æC 
  65942.  
  65943. æKY smScriptNumber
  65944. æFc Script.h
  65945. æT #define
  65946. æD #define smScriptNumber 16 /*Script itl0 id from dictionary.*/
  65947. æC 
  65948.  
  65949. æKY smScriptDate
  65950. æFc Script.h
  65951. æT #define
  65952. æD #define smScriptDate 18 /*Script itl1 id from dictionary.*/
  65953. æC 
  65954.  
  65955. æKY smScriptSort
  65956. æFc Script.h
  65957. æT #define
  65958. æD #define smScriptSort 20 /*Script itl2 id from dictionary.*/
  65959. æC 
  65960.  
  65961. æKY smScriptFlags
  65962. æFc Script.h
  65963. æT #define
  65964. æD #define smScriptFlags 22 /*flags word.*/
  65965. æC 
  65966.   /* GetScript verbs */
  65967.  
  65968.   smScriptVersion    0        Software version
  65969.   smScriptMunged     2        Script entry changed count
  65970.   smScriptEnabled    4        Script enabled flag
  65971.   smScriptRight      6        Right-to-left flag
  65972.   smScriptJust       8        Justification flag
  65973.   smScriptRedraw     10       Word redraw flag
  65974.   smScriptSysFond    12       Preferred system font
  65975.   smScriptAppFond    14       Preferred application font
  65976.   smScriptNumber     16       Script 'itl0' ID, from dictionary
  65977.   smScriptDate       18       Script 'itl1' ID, from dictionary
  65978.   smScriptSort       20       Script 'itl2' ID, from dictionary
  65979.   smScriptFlags      22       Script Flags Word
  65980.   smScriptToken      24       'itl4' ID number
  65981.   smScriptRsvd3      26       Reserved
  65982.   smScriptLang       28       Script’s language code
  65983.   smScriptNumDate    30       Number/Date Representation codes
  65984.   smScriptKeys       32       Script 'KCHR' ID, from dictionary
  65985.   smScriptIcon       34       Script 'SICN' ID, from dictionary
  65986.   smScriptPrint      36       Script printer action routine
  65987.   smScriptTrap       38       Trap entry pointer
  65988.   smScriptCreator    40       Script file creator
  65989.   smScriptFile       42       Script file name
  65990.   smScriptName       44       Script name
  65991.  
  65992. æKY smScriptToken
  65993. æFc Script.h
  65994. æT #define
  65995. æD #define smScriptToken 24 /*Script itl3 id, from dictionary.*/
  65996. æC 
  65997.  
  65998. æKY smScriptRsvd3
  65999. æFc Script.h
  66000. æT #define
  66001. æD #define smScriptRsvd3 26 /*reserved.*/
  66002. æC 
  66003.  
  66004. æKY smScriptLang
  66005. æFc Script.h
  66006. æT #define
  66007. æD #define smScriptLang 28 /*Current language for script.*/
  66008. æC 
  66009.  
  66010. æKY smScriptNumDate
  66011. æFc Script.h
  66012. æT #define
  66013. æD #define smScriptNumDate 30 /*Script Number/Date formats.*/
  66014. æC 
  66015.  
  66016. æKY smScriptKeys
  66017. æFc Script.h
  66018. æT #define
  66019. æD #define smScriptKeys 32 /*Script KEYC id from dictionary.*/
  66020. æC 
  66021.  
  66022. æKY smScriptIcon
  66023. æFc Script.h
  66024. æT #define
  66025. æD #define smScriptIcon 34 /*Script SICN id from dictionary.*/
  66026. æC 
  66027.  
  66028. æKY smScriptPrint
  66029. æFc Script.h
  66030. æT #define
  66031. æD #define smScriptPrint 36 /*Script printer action routine.*/
  66032. æC 
  66033.  
  66034. æKY smScriptTrap
  66035. æFc Script.h
  66036. æT #define
  66037. æD #define smScriptTrap 38 /*Trap entry pointer.*/
  66038. æC 
  66039.  
  66040. æKY smScriptCreator
  66041. æFc Script.h
  66042. æT #define
  66043. æD #define smScriptCreator 40 /*Script file creator.*/
  66044. æC 
  66045.  
  66046. æKY smScriptFile
  66047. æFc Script.h
  66048. æT #define
  66049. æD #define smScriptFile 42 /*Script file name.*/
  66050. æC 
  66051.  
  66052. æKY smScriptName
  66053. æFc Script.h
  66054. æT #define
  66055. æD #define smScriptName 44 /*Script name.*/
  66056. æC 
  66057.  
  66058. æKY smScriptMonoFondSize
  66059. æFc Script.h
  66060. æT #define
  66061. æD 
  66062. /* There is a hole here for old Kanji private verbs 46-76 */
  66063.  
  66064. #define smScriptMonoFondSize 78 /*default monospace FOND (hi) & size (lo).*/
  66065. æC 
  66066.  
  66067. æKY smScriptPrefFondSize
  66068. æFc Script.h
  66069. æT #define
  66070. æD #define smScriptPrefFondSize 80 /*preferred FOND (hi) & size (lo).*/
  66071. æC 
  66072.  
  66073. æKY smScriptSmallFondSize
  66074. æFc Script.h
  66075. æT #define
  66076. æD #define smScriptSmallFondSize 82 /*default small FOND (hi) & size (lo).*/
  66077. æC 
  66078.  
  66079. æKY smScriptSysFondSize
  66080. æFc Script.h
  66081. æT #define
  66082. æD #define smScriptSysFondSize 84 /*default system FOND (hi) & size (lo).*/
  66083. æC 
  66084.  
  66085. æKY smScriptAppFondSize
  66086. æFc Script.h
  66087. æT #define
  66088. æD #define smScriptAppFondSize 86 /*default aoo FOND (hi) & size (lo).*/
  66089. æC 
  66090.  
  66091. æKY smScriptHelpFondSize
  66092. æFc Script.h
  66093. æT #define
  66094. æD #define smScriptHelpFondSize 88 /*default Hep Mgr FOND (hi) & size (lo).*/
  66095. æC 
  66096.  
  66097. æKY smKeyNextScript
  66098. æFc Script.h
  66099. æT #define
  66100. æD 
  66101. /* Negative verbs for KeyScript */
  66102.  
  66103. #define smKeyNextScript -1 /* Switch to next available script */
  66104. æC 
  66105.  
  66106. æKY smKeySysScript
  66107. æFc Script.h
  66108. æT #define
  66109. æD #define smKeySysScript -2 /* Switch to system script */
  66110. æC 
  66111.  
  66112. æKY smKeyLastScript
  66113. æFc Script.h
  66114. æT #define
  66115. æD #define smKeyLastScript -3 /* Switch to last script */
  66116. æC 
  66117.  
  66118. æKY smKeyNextKybd
  66119. æFc Script.h
  66120. æT #define
  66121. æD 
  66122. /* New for System 7.0: */
  66123.  
  66124. #define smKeyNextKybd -4 /* Switch to next keyboard in current script */
  66125. æC 
  66126.  
  66127. æKY smsfIntellCP
  66128. æFc Script.h
  66129. æT #define
  66130. æD 
  66131. /* Bits in the smScriptFlags word
  66132. (bits above 7 are non-static) */
  66133.  
  66134. #define smsfIntellCP 0 /*script has intellegent cut & paste*/
  66135. æC 
  66136.  
  66137. æKY smsfSingByte
  66138. æFc Script.h
  66139. æT #define
  66140. æD #define smsfSingByte 1 /*script has only single bytes*/
  66141. æC 
  66142.  
  66143. æKY smsfNatCase
  66144. æFc Script.h
  66145. æT #define
  66146. æD #define smsfNatCase 2 /*native chars have upper & lower case*/
  66147. æC 
  66148.  
  66149. æKY smsfContext
  66150. æFc Script.h
  66151. æT #define
  66152. æD #define smsfContext 3 /*contextual script (e.g. AIS-based)*/
  66153. æC 
  66154.  
  66155. æKY smsfNoForceFont
  66156. æFc Script.h
  66157. æT #define
  66158. æD #define smsfNoForceFont 4 /*Will not force characters.*/
  66159. æC 
  66160.  
  66161. æKY smsfB0Digits
  66162. æFc Script.h
  66163. æT #define
  66164. æD #define smsfB0Digits 5 /*Has alternate digits at B0-B9.*/
  66165. æC 
  66166.  
  66167. æKY smsfAutoInit
  66168. æFc Script.h
  66169. æT #define
  66170. æD #define smsfAutoInit 6 /*auto initialize the script.*/
  66171. æC 
  66172.  
  66173. æKY smsfForms
  66174. æFc Script.h
  66175. æT #define
  66176. æD #define smsfForms 13 /*Uses contextual forms for letters.*/
  66177. æC 
  66178.  
  66179. æKY smsfLigatures
  66180. æFc Script.h
  66181. æT #define
  66182. æD #define smsfLigatures 14 /*Uses contextual ligatures.*/
  66183. æC 
  66184.  
  66185. æKY smsfReverse
  66186. æFc Script.h
  66187. æT #define
  66188. æD #define smsfReverse 15 /*Reverses native text, right-left.*/
  66189. æC 
  66190.  
  66191. æKY smfShowIcon
  66192. æFc Script.h
  66193. æT #define
  66194. æD 
  66195. /* Bits in the smGenFlags long.
  66196. First byte is set from itlc flags byte. */
  66197.  
  66198. #define smfShowIcon 31 /*Show icon even if only one script.*/
  66199. æC 
  66200.  
  66201. æKY smfDualCaret
  66202. æFc Script.h
  66203. æT #define
  66204. æD #define smfDualCaret 30 /*Use dual caret for mixed direction text.*/
  66205. æC 
  66206.  
  66207. æKY romanSysFond
  66208. æFc Script.h
  66209. æT #define
  66210. æD #define romanSysFond 0x3FFF /*system font id number*/
  66211. æC 
  66212.  
  66213. æKY romanAppFond
  66214. æFc Script.h
  66215. æT #define
  66216. æD #define romanAppFond 3 /*application font id number.*/
  66217. æC 
  66218.  
  66219. æKY romanFlags
  66220. æFc Script.h
  66221. æT #define
  66222. æD #define romanFlags 0x0007 /*roman settings*/
  66223. æC 
  66224.  
  66225. æKY smFondStart
  66226. æFc Script.h
  66227. æT #define
  66228. æD 
  66229. /* Script Manager font equates. */
  66230.  
  66231. #define smFondStart 0x4000 /*start from 16K.*/
  66232. æC 
  66233.  
  66234. æKY smFondEnd
  66235. æFc Script.h
  66236. æT #define
  66237. æD #define smFondEnd 0xC000 /*past end of range at 48K.*/
  66238. æC 
  66239.  
  66240. æKY smUprHalfCharSet
  66241. æFc Script.h
  66242. æT #define
  66243. æD 
  66244. /* Miscellaneous font equates. */
  66245.  
  66246. #define smUprHalfCharSet 0x80 /*first char code in top half of std char set*/
  66247. æC 
  66248.  
  66249. æKY diaeresisUprY
  66250. æFc Script.h
  66251. æT #define
  66252. æD 
  66253. /* Character Set Extensions */
  66254.  
  66255. #define diaeresisUprY 0xD9
  66256. æC 
  66257.  
  66258. æKY fraction
  66259. æFc Script.h
  66260. æT #define
  66261. æD #define fraction 0xDA
  66262. æC 
  66263.  
  66264. æKY intlCurrency
  66265. æFc Script.h
  66266. æT #define
  66267. æD #define intlCurrency 0xDB
  66268. æC 
  66269.  
  66270. æKY leftSingGuillemet
  66271. æFc Script.h
  66272. æT #define
  66273. æD #define leftSingGuillemet 0xDC
  66274. æC 
  66275.  
  66276. æKY rightSingGuillemet
  66277. æFc Script.h
  66278. æT #define
  66279. æD #define rightSingGuillemet 0xDD
  66280. æC 
  66281.  
  66282. æKY fiLigature
  66283. æFc Script.h
  66284. æT #define
  66285. æD #define fiLigature 0xDE
  66286. æC 
  66287.  
  66288. æKY flLigature
  66289. æFc Script.h
  66290. æT #define
  66291. æD #define flLigature 0xDF
  66292. æC 
  66293.  
  66294. æKY dblDagger
  66295. æFc Script.h
  66296. æT #define
  66297. æD #define dblDagger 0xE0
  66298. æC 
  66299.  
  66300. æKY centeredDot
  66301. æFc Script.h
  66302. æT #define
  66303. æD #define centeredDot 0xE1
  66304. æC 
  66305.  
  66306. æKY baseSingQuote
  66307. æFc Script.h
  66308. æT #define
  66309. æD #define baseSingQuote 0xE2
  66310. æC 
  66311.  
  66312. æKY baseDblQuote
  66313. æFc Script.h
  66314. æT #define
  66315. æD #define baseDblQuote 0xE3
  66316. æC 
  66317.  
  66318. æKY perThousand
  66319. æFc Script.h
  66320. æT #define
  66321. æD #define perThousand 0xE4
  66322. æC 
  66323.  
  66324. æKY circumflexUprA
  66325. æFc Script.h
  66326. æT #define
  66327. æD #define circumflexUprA 0xE5
  66328. æC 
  66329.  
  66330. æKY circumflexUprE
  66331. æFc Script.h
  66332. æT #define
  66333. æD #define circumflexUprE 0xE6
  66334. æC 
  66335.  
  66336. æKY acuteUprA
  66337. æFc Script.h
  66338. æT #define
  66339. æD #define acuteUprA 0xE7
  66340. æC 
  66341.  
  66342. æKY diaeresisUprE
  66343. æFc Script.h
  66344. æT #define
  66345. æD #define diaeresisUprE 0xE8
  66346. æC 
  66347.  
  66348. æKY graveUprE
  66349. æFc Script.h
  66350. æT #define
  66351. æD #define graveUprE 0xE9
  66352. æC 
  66353.  
  66354. æKY acuteUprI
  66355. æFc Script.h
  66356. æT #define
  66357. æD #define acuteUprI 0xEA
  66358. æC 
  66359.  
  66360. æKY circumflexUprI
  66361. æFc Script.h
  66362. æT #define
  66363. æD #define circumflexUprI 0xEB
  66364. æC 
  66365.  
  66366. æKY diaeresisUprI
  66367. æFc Script.h
  66368. æT #define
  66369. æD #define diaeresisUprI 0xEC
  66370. æC 
  66371.  
  66372. æKY graveUprI
  66373. æFc Script.h
  66374. æT #define
  66375. æD #define graveUprI 0xED
  66376. æC 
  66377.  
  66378. æKY acuteUprO
  66379. æFc Script.h
  66380. æT #define
  66381. æD #define acuteUprO 0xEE
  66382. æC 
  66383.  
  66384. æKY circumflexUprO
  66385. æFc Script.h
  66386. æT #define
  66387. æD #define circumflexUprO 0xEF
  66388. æC 
  66389.  
  66390. æKY appleLogo
  66391. æFc Script.h
  66392. æT #define
  66393. æD #define appleLogo 0xF0
  66394. æC 
  66395.  
  66396. æKY graveUprO
  66397. æFc Script.h
  66398. æT #define
  66399. æD #define graveUprO 0xF1
  66400. æC 
  66401.  
  66402. æKY acuteUprU
  66403. æFc Script.h
  66404. æT #define
  66405. æD #define acuteUprU 0xF2
  66406. æC 
  66407.  
  66408. æKY circumflexUprU
  66409. æFc Script.h
  66410. æT #define
  66411. æD #define circumflexUprU 0xF3
  66412. æC 
  66413.  
  66414. æKY graveUprU
  66415. æFc Script.h
  66416. æT #define
  66417. æD #define graveUprU 0xF4
  66418. æC 
  66419.  
  66420. æKY dotlessLwrI
  66421. æFc Script.h
  66422. æT #define
  66423. æD #define dotlessLwrI 0xF5
  66424. æC 
  66425.  
  66426. æKY circumflex
  66427. æFc Script.h
  66428. æT #define
  66429. æD #define circumflex 0xF6
  66430. æC 
  66431.  
  66432. æKY tilde
  66433. æFc Script.h
  66434. æT #define
  66435. æD #define tilde 0xF7
  66436. æC 
  66437.  
  66438. æKY macron
  66439. æFc Script.h
  66440. æT #define
  66441. æD #define macron 0xF8
  66442. æC 
  66443.  
  66444. æKY breve
  66445. æFc Script.h
  66446. æT #define
  66447. æD #define breve 0xF9
  66448. æC 
  66449.  
  66450. æKY overDot
  66451. æFc Script.h
  66452. æT #define
  66453. æD #define overDot 0xFA
  66454. æC 
  66455.  
  66456. æKY ring
  66457. æFc Script.h
  66458. æT #define
  66459. æD #define ring 0xFB
  66460. æC 
  66461.  
  66462. æKY cedilla
  66463. æFc Script.h
  66464. æT #define
  66465. æD #define cedilla 0xFC
  66466. æC 
  66467.  
  66468. æKY doubleAcute
  66469. æFc Script.h
  66470. æT #define
  66471. æD #define doubleAcute 0xFD
  66472. æC 
  66473.  
  66474. æKY ogonek
  66475. æFc Script.h
  66476. æT #define
  66477. æD #define ogonek 0xFE
  66478. æC 
  66479.  
  66480. æKY hachek
  66481. æFc Script.h
  66482. æT #define
  66483. æD #define hachek 0xFF
  66484. æC 
  66485.  
  66486. æKY fatalDateTime
  66487. æFc Script.h
  66488. æT #define
  66489. æD 
  66490. /* String2Date status values */
  66491.  
  66492. #define fatalDateTime 0x8000
  66493. æC 
  66494.  
  66495. æKY longDateFound
  66496. æFc Script.h
  66497. æT #define
  66498. æD #define longDateFound 1
  66499. æC 
  66500.  
  66501. æKY leftOverChars
  66502. æFc Script.h
  66503. æT #define
  66504. æD #define leftOverChars 2
  66505. æC 
  66506.  
  66507. æKY sepNotIntlSep
  66508. æFc Script.h
  66509. æT #define
  66510. æD #define sepNotIntlSep 4
  66511. æC 
  66512.  
  66513. æKY fieldOrderNotIntl
  66514. æFc Script.h
  66515. æT #define
  66516. æD #define fieldOrderNotIntl 8
  66517. æC 
  66518.  
  66519. æKY extraneousStrings
  66520. æFc Script.h
  66521. æT #define
  66522. æD #define extraneousStrings 16
  66523. æC 
  66524.  
  66525. æKY tooManySeps
  66526. æFc Script.h
  66527. æT #define
  66528. æD #define tooManySeps 32
  66529. æC 
  66530.  
  66531. æKY sepNotConsistent
  66532. æFc Script.h
  66533. æT #define
  66534. æD #define sepNotConsistent 64
  66535. æC 
  66536.  
  66537. æKY tokenErr
  66538. æFc Script.h
  66539. æT #define
  66540. æD #define tokenErr 0x8100
  66541. æC 
  66542.  
  66543. æKY cantReadUtilities
  66544. æFc Script.h
  66545. æT #define
  66546. æD #define cantReadUtilities 0x8200
  66547. æC 
  66548.  
  66549. æKY dateTimeNotFound
  66550. æFc Script.h
  66551. æT #define
  66552. æD #define dateTimeNotFound 0x8400
  66553. æC 
  66554.  
  66555. æKY dateTimeInvalid
  66556. æFc Script.h
  66557. æT #define
  66558. æD #define dateTimeInvalid 0x8800
  66559. æC 
  66560.  
  66561. æKY tokenIntl
  66562. æFc Script.h
  66563. æT #define
  66564. æD 
  66565. /* TokenType values */
  66566.  
  66567. #define tokenIntl 4 /*the itl resource number of the tokenizer*/
  66568. æC 
  66569.  
  66570. æKY tokenEmpty
  66571. æFc Script.h
  66572. æT #define
  66573. æD #define tokenEmpty -1
  66574. æC 
  66575.  
  66576. æKY tokenUnknown
  66577. æFc Script.h
  66578. æT #define
  66579. æD #define tokenUnknown 0
  66580. æC 
  66581.  
  66582. æKY tokenWhite
  66583. æFc Script.h
  66584. æT #define
  66585. æD #define tokenWhite 1
  66586. æC 
  66587.  
  66588. æKY tokenLeftLit
  66589. æFc Script.h
  66590. æT #define
  66591. æD #define tokenLeftLit 2
  66592. æC 
  66593.  
  66594. æKY tokenRightLit
  66595. æFc Script.h
  66596. æT #define
  66597. æD #define tokenRightLit 3
  66598. æC 
  66599.  
  66600. æKY tokenAlpha
  66601. æFc Script.h
  66602. æT #define
  66603. æD #define tokenAlpha 4
  66604. æC 
  66605.  
  66606. æKY tokenNumeric
  66607. æFc Script.h
  66608. æT #define
  66609. æD #define tokenNumeric 5
  66610. æC 
  66611.  
  66612. æKY tokenNewLine
  66613. æFc Script.h
  66614. æT #define
  66615. æD #define tokenNewLine 6
  66616. æC 
  66617.  
  66618. æKY tokenLeftComment
  66619. æFc Script.h
  66620. æT #define
  66621. æD #define tokenLeftComment 7
  66622. æC 
  66623.  
  66624. æKY tokenRightComment
  66625. æFc Script.h
  66626. æT #define
  66627. æD #define tokenRightComment 8
  66628. æC 
  66629.  
  66630. æKY tokenLiteral
  66631. æFc Script.h
  66632. æT #define
  66633. æD #define tokenLiteral 9
  66634. æC 
  66635.  
  66636. æKY tokenEscape
  66637. æFc Script.h
  66638. æT #define
  66639. æD #define tokenEscape 10
  66640. æC 
  66641.  
  66642. æKY tokenAltNum
  66643. æFc Script.h
  66644. æT #define
  66645. æD #define tokenAltNum 11
  66646. æC 
  66647.  
  66648. æKY tokenRealNum
  66649. æFc Script.h
  66650. æT #define
  66651. æD #define tokenRealNum 12
  66652. æC 
  66653.  
  66654. æKY tokenAltReal
  66655. æFc Script.h
  66656. æT #define
  66657. æD #define tokenAltReal 13
  66658. æC 
  66659.  
  66660. æKY tokenReserve1
  66661. æFc Script.h
  66662. æT #define
  66663. æD #define tokenReserve1 14
  66664. æC 
  66665.  
  66666. æKY tokenReserve2
  66667. æFc Script.h
  66668. æT #define
  66669. æD #define tokenReserve2 15
  66670. æC 
  66671.  
  66672. æKY tokenLeftParen
  66673. æFc Script.h
  66674. æT #define
  66675. æD #define tokenLeftParen 16
  66676. æC 
  66677.  
  66678. æKY tokenRightParen
  66679. æFc Script.h
  66680. æT #define
  66681. æD #define tokenRightParen 17
  66682. æC 
  66683.  
  66684. æKY tokenLeftBracket
  66685. æFc Script.h
  66686. æT #define
  66687. æD #define tokenLeftBracket 18
  66688. æC 
  66689.  
  66690. æKY tokenRightBracket
  66691. æFc Script.h
  66692. æT #define
  66693. æD #define tokenRightBracket 19
  66694. æC 
  66695.  
  66696. æKY tokenLeftCurly
  66697. æFc Script.h
  66698. æT #define
  66699. æD #define tokenLeftCurly 20
  66700. æC 
  66701.  
  66702. æKY tokenRightCurly
  66703. æFc Script.h
  66704. æT #define
  66705. æD #define tokenRightCurly 21
  66706. æC 
  66707.  
  66708. æKY tokenLeftEnclose
  66709. æFc Script.h
  66710. æT #define
  66711. æD #define tokenLeftEnclose 22
  66712. æC 
  66713.  
  66714. æKY tokenRightEnclose
  66715. æFc Script.h
  66716. æT #define
  66717. æD #define tokenRightEnclose 23
  66718. æC 
  66719.  
  66720. æKY tokenPlus
  66721. æFc Script.h
  66722. æT #define
  66723. æD #define tokenPlus 24
  66724. æC 
  66725.  
  66726. æKY tokenMinus
  66727. æFc Script.h
  66728. æT #define
  66729. æD #define tokenMinus 25
  66730. æC 
  66731.  
  66732. æKY tokenAsterisk
  66733. æFc Script.h
  66734. æT #define
  66735. æD #define tokenAsterisk 26
  66736. æC 
  66737.  
  66738. æKY tokenDivide
  66739. æFc Script.h
  66740. æT #define
  66741. æD #define tokenDivide 27
  66742. æC 
  66743.  
  66744. æKY tokenPlusMinus
  66745. æFc Script.h
  66746. æT #define
  66747. æD #define tokenPlusMinus 28
  66748. æC 
  66749.  
  66750. æKY tokenSlash
  66751. æFc Script.h
  66752. æT #define
  66753. æD #define tokenSlash 29
  66754. æC 
  66755.  
  66756. æKY tokenBackSlash
  66757. æFc Script.h
  66758. æT #define
  66759. æD #define tokenBackSlash 30
  66760. æC 
  66761.  
  66762. æKY tokenLess
  66763. æFc Script.h
  66764. æT #define
  66765. æD #define tokenLess 31
  66766. æC 
  66767.  
  66768. æKY tokenGreat
  66769. æFc Script.h
  66770. æT #define
  66771. æD #define tokenGreat 32
  66772. æC 
  66773.  
  66774. æKY tokenEqual
  66775. æFc Script.h
  66776. æT #define
  66777. æD #define tokenEqual 33
  66778. æC 
  66779.  
  66780. æKY tokenLessEqual2
  66781. æFc Script.h
  66782. æT #define
  66783. æD #define tokenLessEqual2 34
  66784. æC 
  66785.  
  66786. æKY tokenLessEqual1
  66787. æFc Script.h
  66788. æT #define
  66789. æD #define tokenLessEqual1 35
  66790. æC 
  66791.  
  66792. æKY tokenGreatEqual2
  66793. æFc Script.h
  66794. æT #define
  66795. æD #define tokenGreatEqual2 36
  66796. æC 
  66797.  
  66798. æKY tokenGreatEqual1
  66799. æFc Script.h
  66800. æT #define
  66801. æD #define tokenGreatEqual1 37
  66802. æC 
  66803.  
  66804. æKY token2Equal
  66805. æFc Script.h
  66806. æT #define
  66807. æD #define token2Equal 38
  66808. æC 
  66809.  
  66810. æKY tokenColonEqual
  66811. æFc Script.h
  66812. æT #define
  66813. æD #define tokenColonEqual 39
  66814. æC 
  66815.  
  66816. æKY tokenNotEqual
  66817. æFc Script.h
  66818. æT #define
  66819. æD #define tokenNotEqual 40
  66820. æC 
  66821.  
  66822. æKY tokenLessGreat
  66823. æFc Script.h
  66824. æT #define
  66825. æD #define tokenLessGreat 41
  66826. æC 
  66827.  
  66828. æKY tokenExclamEqual
  66829. æFc Script.h
  66830. æT #define
  66831. æD #define tokenExclamEqual 42
  66832. æC 
  66833.  
  66834. æKY tokenExclam
  66835. æFc Script.h
  66836. æT #define
  66837. æD #define tokenExclam 43
  66838. æC 
  66839.  
  66840. æKY tokenTilda
  66841. æFc Script.h
  66842. æT #define
  66843. æD #define tokenTilda 44
  66844. æC 
  66845.  
  66846. æKY tokenComma
  66847. æFc Script.h
  66848. æT #define
  66849. æD #define tokenComma 45
  66850. æC 
  66851.  
  66852. æKY tokenPeriod
  66853. æFc Script.h
  66854. æT #define
  66855. æD #define tokenPeriod 46
  66856. æC 
  66857.  
  66858. æKY tokenLeft2Quote
  66859. æFc Script.h
  66860. æT #define
  66861. æD #define tokenLeft2Quote 47
  66862. æC 
  66863.  
  66864. æKY tokenRight2Quote
  66865. æFc Script.h
  66866. æT #define
  66867. æD #define tokenRight2Quote 48
  66868. æC 
  66869.  
  66870. æKY tokenLeft1Quote
  66871. æFc Script.h
  66872. æT #define
  66873. æD #define tokenLeft1Quote 49
  66874. æC 
  66875.  
  66876. æKY tokenRight1Quote
  66877. æFc Script.h
  66878. æT #define
  66879. æD #define tokenRight1Quote 50
  66880. æC 
  66881.  
  66882. æKY token2Quote
  66883. æFc Script.h
  66884. æT #define
  66885. æD #define token2Quote 51
  66886. æC 
  66887.  
  66888. æKY token1Quote
  66889. æFc Script.h
  66890. æT #define
  66891. æD #define token1Quote 52
  66892. æC 
  66893.  
  66894. æKY tokenSemicolon
  66895. æFc Script.h
  66896. æT #define
  66897. æD #define tokenSemicolon 53
  66898. æC 
  66899.  
  66900. æKY tokenPercent
  66901. æFc Script.h
  66902. æT #define
  66903. æD #define tokenPercent 54
  66904. æC 
  66905.  
  66906. æKY tokenCarat
  66907. æFc Script.h
  66908. æT #define
  66909. æD #define tokenCarat 55
  66910. æC 
  66911.  
  66912. æKY tokenUnderline
  66913. æFc Script.h
  66914. æT #define
  66915. æD #define tokenUnderline 56
  66916. æC 
  66917.  
  66918. æKY tokenAmpersand
  66919. æFc Script.h
  66920. æT #define
  66921. æD #define tokenAmpersand 57
  66922. æC 
  66923.  
  66924. æKY tokenAtSign
  66925. æFc Script.h
  66926. æT #define
  66927. æD #define tokenAtSign 58
  66928. æC 
  66929.  
  66930. æKY tokenBar
  66931. æFc Script.h
  66932. æT #define
  66933. æD #define tokenBar 59
  66934. æC 
  66935.  
  66936. æKY tokenQuestion
  66937. æFc Script.h
  66938. æT #define
  66939. æD #define tokenQuestion 60
  66940. æC 
  66941.  
  66942. æKY tokenPi
  66943. æFc Script.h
  66944. æT #define
  66945. æD #define tokenPi 61
  66946. æC 
  66947.  
  66948. æKY tokenRoot
  66949. æFc Script.h
  66950. æT #define
  66951. æD #define tokenRoot 62
  66952. æC 
  66953.  
  66954. æKY tokenSigma
  66955. æFc Script.h
  66956. æT #define
  66957. æD #define tokenSigma 63
  66958. æC 
  66959.  
  66960. æKY tokenIntegral
  66961. æFc Script.h
  66962. æT #define
  66963. æD #define tokenIntegral 64
  66964. æC 
  66965.  
  66966. æKY tokenMicro
  66967. æFc Script.h
  66968. æT #define
  66969. æD #define tokenMicro 65
  66970. æC 
  66971.  
  66972. æKY tokenCapPi
  66973. æFc Script.h
  66974. æT #define
  66975. æD #define tokenCapPi 66
  66976. æC 
  66977.  
  66978. æKY tokenInfinity
  66979. æFc Script.h
  66980. æT #define
  66981. æD #define tokenInfinity 67
  66982. æC 
  66983.  
  66984. æKY tokenColon
  66985. æFc Script.h
  66986. æT #define
  66987. æD #define tokenColon 68
  66988. æC 
  66989.  
  66990. æKY tokenHash
  66991. æFc Script.h
  66992. æT #define
  66993. æD #define tokenHash 69
  66994. æC 
  66995.  
  66996. æKY tokenDollar
  66997. æFc Script.h
  66998. æT #define
  66999. æD #define tokenDollar 70
  67000. æC 
  67001.  
  67002. æKY tokenNoBreakSpace
  67003. æFc Script.h
  67004. æT #define
  67005. æD #define tokenNoBreakSpace 71
  67006. æC 
  67007.  
  67008. æKY tokenFraction
  67009. æFc Script.h
  67010. æT #define
  67011. æD #define tokenFraction 72
  67012. æC 
  67013.  
  67014. æKY tokenIntlCurrency
  67015. æFc Script.h
  67016. æT #define
  67017. æD #define tokenIntlCurrency 73
  67018. æC 
  67019.  
  67020. æKY tokenLeftSingGuillemet
  67021. æFc Script.h
  67022. æT #define
  67023. æD #define tokenLeftSingGuillemet 74
  67024. æC 
  67025.  
  67026. æKY tokenRightSingGuillemet
  67027. æFc Script.h
  67028. æT #define
  67029. æD #define tokenRightSingGuillemet 75
  67030. æC 
  67031.  
  67032. æKY tokenPerThousand
  67033. æFc Script.h
  67034. æT #define
  67035. æD #define tokenPerThousand 76
  67036. æC 
  67037.  
  67038. æKY tokenNil
  67039. æFc Script.h
  67040. æT #define
  67041. æD #define tokenNil 127
  67042. æC 
  67043.  
  67044. æKY delimPad
  67045. æFc Script.h
  67046. æT #define
  67047. æD #define delimPad -2
  67048. æC 
  67049.  
  67050. æKY tokLeftQuote
  67051. æFc Script.h
  67052. æT #define
  67053. æD 
  67054. /* the NumberParts indices */
  67055.  
  67056. #define tokLeftQuote 1
  67057. æC 
  67058.  
  67059. æKY tokRightQuote
  67060. æFc Script.h
  67061. æT #define
  67062. æD #define tokRightQuote 2
  67063. æC 
  67064.  
  67065. æKY tokLeadPlacer
  67066. æFc Script.h
  67067. æT #define
  67068. æD #define tokLeadPlacer 3
  67069. æC 
  67070.  
  67071. æKY tokLeader
  67072. æFc Script.h
  67073. æT #define
  67074. æD #define tokLeader 4
  67075. æC 
  67076.  
  67077. æKY tokNonLeader
  67078. æFc Script.h
  67079. æT #define
  67080. æD #define tokNonLeader 5
  67081. æC 
  67082.  
  67083. æKY tokZeroLead
  67084. æFc Script.h
  67085. æT #define
  67086. æD #define tokZeroLead 6
  67087. æC 
  67088.  
  67089. æKY tokPercent
  67090. æFc Script.h
  67091. æT #define
  67092. æD #define tokPercent 7
  67093. æC 
  67094.  
  67095. æKY tokPlusSign
  67096. æFc Script.h
  67097. æT #define
  67098. æD #define tokPlusSign 8
  67099. æC 
  67100.  
  67101. æKY tokMinusSign
  67102. æFc Script.h
  67103. æT #define
  67104. æD #define tokMinusSign 9
  67105. æC 
  67106.  
  67107. æKY tokThousands
  67108. æFc Script.h
  67109. æT #define
  67110. æD #define tokThousands 10
  67111. æC 
  67112.  
  67113. æKY tokSeparator
  67114. æFc Script.h
  67115. æT #define
  67116. æD #define tokSeparator 12 /*11 is a reserved field*/
  67117. æC 
  67118.  
  67119. æKY tokEscape
  67120. æFc Script.h
  67121. æT #define
  67122. æD #define tokEscape 13
  67123. æC 
  67124.  
  67125. æKY tokDecPoint
  67126. æFc Script.h
  67127. æT #define
  67128. æD #define tokDecPoint 14
  67129. æC 
  67130.  
  67131. æKY tokEPlus
  67132. æFc Script.h
  67133. æT #define
  67134. æD #define tokEPlus 15
  67135. æC 
  67136.  
  67137. æKY tokEMinus
  67138. æFc Script.h
  67139. æT #define
  67140. æD #define tokEMinus 16
  67141. æC 
  67142.  
  67143. æKY tokMaxSymbols
  67144. æFc Script.h
  67145. æT #define
  67146. æD #define tokMaxSymbols 31
  67147. æC 
  67148.  
  67149. æKY curNumberPartsVersion
  67150. æFc Script.h
  67151. æT #define
  67152. æD #define curNumberPartsVersion 1 /*current version of NumberParts record*/
  67153. æC 
  67154.  
  67155. æKY smallDateBit
  67156. æFc Script.h
  67157. æT #define
  67158. æD 
  67159. /*  Date equates */
  67160.  
  67161. #define smallDateBit 31 /*Restrict valid date/time to range of Time global*/
  67162. æC 
  67163.  
  67164. æKY togChar12HourBit
  67165. æFc Script.h
  67166. æT #define
  67167. æD #define togChar12HourBit 30 /*If toggling hour by char, accept hours 1..12 only*/
  67168. æC 
  67169.  
  67170. æKY togCharZCycleBit
  67171. æFc Script.h
  67172. æT #define
  67173. æD #define togCharZCycleBit 29 /*Modifier for togChar12HourBit: accept hours 0..11 only*/
  67174. æC 
  67175.  
  67176. æKY togDelta12HourBit
  67177. æFc Script.h
  67178. æT #define
  67179. æD #define togDelta12HourBit 28 /*If toggling hour up/down, restrict to 12-hour range (am/pm)*/
  67180. æC 
  67181.  
  67182. æKY genCdevRangeBit
  67183. æFc Script.h
  67184. æT #define
  67185. æD #define genCdevRangeBit 27 /*Restrict date/time to range used by genl CDEV*/
  67186. æC 
  67187.  
  67188. æKY validDateFields
  67189. æFc Script.h
  67190. æT #define
  67191. æD #define validDateFields -1
  67192. æC 
  67193.  
  67194. æKY maxDateField
  67195. æFc Script.h
  67196. æT #define
  67197. æD #define maxDateField 10
  67198. æC 
  67199.  
  67200. æKY eraMask
  67201. æFc Script.h
  67202. æT #define
  67203. æD #define eraMask 0x0001
  67204. æC 
  67205.  
  67206. æKY yearMask
  67207. æFc Script.h
  67208. æT #define
  67209. æD #define yearMask 0x0002
  67210. æC 
  67211.  
  67212. æKY monthMask
  67213. æFc Script.h
  67214. æT #define
  67215. æD #define monthMask 0x0004
  67216. æC 
  67217.  
  67218. æKY dayMask
  67219. æFc Script.h
  67220. æT #define
  67221. æD #define dayMask 0x0008
  67222. æC 
  67223.  
  67224. æKY hourMask
  67225. æFc Script.h
  67226. æT #define
  67227. æD #define hourMask 0x0010
  67228. æC 
  67229.  
  67230. æKY minuteMask
  67231. æFc Script.h
  67232. æT #define
  67233. æD #define minuteMask 0x0020
  67234. æC 
  67235.  
  67236. æKY secondMask
  67237. æFc Script.h
  67238. æT #define
  67239. æD #define secondMask 0x0040
  67240. æC 
  67241.  
  67242. æKY dayOfWeekMask
  67243. æFc Script.h
  67244. æT #define
  67245. æD #define dayOfWeekMask 0x0080
  67246. æC 
  67247.  
  67248. æKY dayOfYearMask
  67249. æFc Script.h
  67250. æT #define
  67251. æD #define dayOfYearMask 0x0100
  67252. æC 
  67253.  
  67254. æKY weekOfYearMask
  67255. æFc Script.h
  67256. æT #define
  67257. æD #define weekOfYearMask 0x0200
  67258. æC 
  67259.  
  67260. æKY pmMask
  67261. æFc Script.h
  67262. æT #define
  67263. æD #define pmMask 0x0400
  67264. æC 
  67265.  
  67266. æKY dateStdMask
  67267. æFc Script.h
  67268. æT #define
  67269. æD #define dateStdMask 0x007F
  67270. æC 
  67271.  
  67272. æKY fVNumber
  67273. æFc Script.h
  67274. æT #define
  67275. æD #define fVNumber 0 /*first version of NumFormatString*/
  67276. æC 
  67277.  
  67278. æKY toggleUndefined
  67279. æFc Script.h
  67280. æT #define
  67281. æD 
  67282. /* Toggle results */
  67283.  
  67284. #define toggleUndefined 0
  67285. æC 
  67286.  
  67287. æKY toggleOK
  67288. æFc Script.h
  67289. æT #define
  67290. æD #define toggleOK 1
  67291. æC 
  67292.  
  67293. æKY toggleBadField
  67294. æFc Script.h
  67295. æT #define
  67296. æD #define toggleBadField 2
  67297. æC 
  67298.  
  67299. æKY toggleBadDelta
  67300. æFc Script.h
  67301. æT #define
  67302. æD #define toggleBadDelta 3
  67303. æC 
  67304.  
  67305. æKY toggleBadChar
  67306. æFc Script.h
  67307. æT #define
  67308. æD #define toggleBadChar 4
  67309. æC 
  67310.  
  67311. æKY toggleUnknown
  67312. æFc Script.h
  67313. æT #define
  67314. æD #define toggleUnknown 5
  67315. æC 
  67316.  
  67317. æKY toggleBadNum
  67318. æFc Script.h
  67319. æT #define
  67320. æD #define toggleBadNum 6
  67321. æC 
  67322.  
  67323. æKY toggleOutOfRange
  67324. æFc Script.h
  67325. æT #define
  67326. æD #define toggleOutOfRange 7 /*synonym for toggleErr3*/
  67327. æC 
  67328.  
  67329. æKY toggleErr3
  67330. æFc Script.h
  67331. æT #define
  67332. æD #define toggleErr3 7
  67333. æC 
  67334.  
  67335. æKY toggleErr4
  67336. æFc Script.h
  67337. æT #define
  67338. æD #define toggleErr4 8
  67339. æC 
  67340.  
  67341. æKY toggleErr5
  67342. æFc Script.h
  67343. æT #define
  67344. æD #define toggleErr5 9
  67345. æC 
  67346.  
  67347. æKY smTruncEnd
  67348. æFc Script.h
  67349. æT #define
  67350. æD 
  67351. /*  Constants for truncWhere argument in TruncString and TruncText  */
  67352.  
  67353. #define smTruncEnd 0 /* Truncate at end */
  67354. æC 
  67355.  
  67356. æKY smTruncMiddle
  67357. æFc Script.h
  67358. æT #define
  67359. æD #define smTruncMiddle 0x4000 /* Truncate in middle */
  67360. æC 
  67361.  
  67362. æKY smNotTruncated
  67363. æFc Script.h
  67364. æT #define
  67365. æD 
  67366. /* Constants for TruncString and TruncText results */
  67367.  
  67368. #define smNotTruncated 0 /* No truncation was necessary */
  67369. æC 
  67370.  
  67371. æKY smTruncated
  67372. æFc Script.h
  67373. æT #define
  67374. æD #define smTruncated 1 /* Truncation performed */
  67375. æC 
  67376.  
  67377. æKY smTruncErr
  67378. æFc Script.h
  67379. æT #define
  67380. æD #define smTruncErr -1 /* General error */
  67381. æC 
  67382.  
  67383. æKY smOnlyStyleRun
  67384. æFc Script.h
  67385. æT #define
  67386. æD 
  67387. /* Constants for styleRunPosition argument in NPortionText, NDrawJust,
  67388.  NMeasureJust, NChar2Pixel, and NPixel2Char. */
  67389.  
  67390. #define smOnlyStyleRun 0 /* This is the only style run on the line.*/
  67391. æC 
  67392.  
  67393. æKY smLeftStyleRun
  67394. æFc Script.h
  67395. æT #define
  67396. æD #define smLeftStyleRun 1 /*This is leftmost of multiple style runs on the line.*/
  67397. æC 
  67398.  
  67399. æKY smRightStyleRun
  67400. æFc Script.h
  67401. æT #define
  67402. æD #define smRightStyleRun 2 /*This is rightmost of multiple style runs on the line.*/
  67403. æC 
  67404.  
  67405. æKY smMiddleStyleRun
  67406. æFc Script.h
  67407. æT #define
  67408. æD #define smMiddleStyleRun 3 /*There are multiple style runs on the line and this is neither the leftmost nor the rightmost.*/
  67409. æC 
  67410.  
  67411. æKY TokenResults
  67412. tokenOK
  67413. tokenOverflow
  67414. stringOverflow
  67415. badDelim
  67416. badEnding
  67417. crash
  67418. æFc Script.h
  67419. æT enum
  67420. æD enum {tokenOK,tokenOverflow,stringOverflow,badDelim,badEnding,crash};
  67421. typedef unsigned char TokenResults;
  67422. æC 
  67423.  
  67424. æKY LongDateField
  67425. eraField
  67426. yearField
  67427. monthField
  67428. dayField
  67429. hourField
  67430. minuteField
  67431. secondField
  67432. dayOfWeekField
  67433. dayOfYearField
  67434. weekOfYearField
  67435. pmField
  67436. res1Field
  67437. res2Field
  67438. res3Field
  67439. æFc Script.h
  67440. æT enum
  67441. æD enum {eraField,yearField,monthField,dayField,hourField,minuteField,secondField,
  67442.     dayOfWeekField,dayOfYearField,weekOfYearField,pmField,res1Field,res2Field,
  67443.     res3Field};
  67444. typedef unsigned char LongDateField;
  67445. æC 
  67446.  
  67447. æKY StyledLineBreakCode
  67448. smBreakWord
  67449. smBreakChar
  67450. smBreakOverflow
  67451. æFc Script.h
  67452. æT enum
  67453. æD enum {smBreakWord,smBreakChar,smBreakOverflow};
  67454. typedef unsigned char StyledLineBreakCode;
  67455. æC 
  67456.  
  67457. æKY FormatClass
  67458. fPositive
  67459. fNegative
  67460. fZero
  67461. æFc Script.h
  67462. æT enum
  67463. æD enum {fPositive,fNegative,fZero};
  67464. typedef unsigned char FormatClass;
  67465. æC 
  67466.  
  67467. æKY FormatResultType
  67468. fFormatOK
  67469. fBestGuess
  67470. fOutOfSynch
  67471. fSpuriousChars
  67472. fMissingDelimiter
  67473. fExtraDecimal
  67474. fMissingLiteral
  67475. fExtraExp
  67476. fFormatOverflow
  67477. fFormStrIsNAN
  67478. fBadPartsTable
  67479. fExtraPercent
  67480. fExtraSeparator
  67481. fEmptyFormatString
  67482. æFc Script.h
  67483. æT enum
  67484. æD enum {fFormatOK,fBestGuess,fOutOfSynch,fSpuriousChars,fMissingDelimiter,
  67485.     fExtraDecimal,fMissingLiteral,fExtraExp,fFormatOverflow,fFormStrIsNAN,
  67486.     fBadPartsTable,fExtraPercent,fExtraSeparator,fEmptyFormatString};
  67487. typedef unsigned char FormatResultType;
  67488. æC 
  67489.  
  67490. æKY CharByteTable
  67491. æFc Script.h
  67492. æT typedef
  67493. æD typedef char CharByteTable[256];
  67494. æC 
  67495.  
  67496. æKY ToggleResults
  67497. æFc Script.h
  67498. æT typedef
  67499. æD typedef short ToggleResults;
  67500. æC 
  67501.  
  67502. æKY TruncCode
  67503. æFc Script.h
  67504. æT typedef
  67505. æD /* type for truncWhere parameter in new TruncString, TruncText */
  67506. typedef short TruncCode;
  67507.  
  67508. æC 
  67509.  
  67510. æKY JustStyleCode
  67511. æFc Script.h
  67512. æT typedef
  67513. æD /* type for styleRunPosition parameter in NPixel2Char etc. */
  67514. typedef short JustStyleCode;
  67515. æC 
  67516.  
  67517. æKY BreakTable
  67518. BreakTablePtr
  67519. æFc Script.h
  67520. æT struct
  67521. æD struct BreakTable {
  67522.     char charTypes[256];
  67523.     short tripleLength;
  67524.     short triples[1];
  67525. };
  67526.  
  67527. typedef struct BreakTable BreakTable;
  67528. typedef BreakTable *BreakTablePtr;
  67529.  
  67530. æC 
  67531.  
  67532. æKY NBreakTable
  67533. NBreakTablePtr
  67534. æFc Script.h
  67535. æT struct
  67536. æD struct NBreakTable {
  67537.     signed char flags1;
  67538.     signed char flags2;
  67539.     short version;
  67540.     short classTableOff;
  67541.     short auxCTableOff;
  67542.     short backwdTableOff;
  67543.     short forwdTableOff;
  67544.     short doBackup;
  67545.     short reserved;
  67546.     char charTypes[256];
  67547.     Integer tables[1];
  67548. };
  67549.  
  67550. typedef struct NBreakTable NBreakTable;
  67551. typedef NBreakTable *NBreakTablePtr;
  67552.  
  67553. æC 
  67554.  
  67555. æKY OffPair
  67556. æFc Script.h
  67557. æT struct
  67558. æD struct OffPair {
  67559.     short offFirst;
  67560.     short offSecond;
  67561. };
  67562.  
  67563. typedef struct OffPair OffPair;
  67564. typedef OffPair OffsetTable[3];
  67565.  
  67566.  
  67567. æC 
  67568.  
  67569. æKY ItlcRecord
  67570. æFc Script.h
  67571. æT struct
  67572. æD struct ItlcRecord {
  67573.     short itlcSystem; /*default system script.*/
  67574.     short itlcReserved; /*reserved*/
  67575.     char itlcFontForce; /*default font force flag*/
  67576.     char itlcIntlForce; /*default intl force flag.*/
  67577.     char itlcOldKybd; /*old keyboard*/
  67578.     char itlcFlags; /*general flags*/
  67579.     short itlcIconOffset; /*script icon offset*/
  67580.     char itlcIconSide; /*icon side*/
  67581.     char itlcIconRsvd; /*rsvd for other icon info*/
  67582.     short itlcRegionCode; /*preferred verXxx code.*/
  67583.     char itlcReserved3[34]; /*for future use*/
  67584. };
  67585.  
  67586. typedef struct ItlcRecord ItlcRecord;
  67587. æC 
  67588.  
  67589. æKY ItlbRecord
  67590. æFc Script.h
  67591. æT struct
  67592. æD struct ItlbRecord {
  67593.     short itlbNumber; /*ITL0 id number.*/
  67594.     short itlbDate; /*ITL1 id number.*/
  67595.     short itlbSort; /*ITL2 id number.*/
  67596.     short itlbFlags; /*Script flags*/
  67597.     short itlbToken; /*ITL4 id number.*/
  67598.     short itlbReserved3; /*reserved.*/
  67599.     short itlbLang; /*cur language for script */
  67600.     char itlbNumRep; /*number representation code*/
  67601.     char itlbDateRep; /*date representation code */
  67602.     short itlbKeys; /*KCHR id number.*/
  67603.     short itlbIcon; /*SICN id number.*/
  67604. };
  67605.  
  67606. typedef struct ItlbRecord ItlbRecord;
  67607. æC 
  67608.  
  67609. æKY ItlbExtRecord
  67610. æFc Script.h
  67611. æT struct
  67612. æD struct ItlbExtRecord {
  67613.     ItlbRecord base; /*un-extended ItlbRecord*/
  67614.     long itlbLocalSize; /*size of script's local record*/
  67615.     short itlbMonoFond; /*default monospace FOND ID*/
  67616.     short itlbMonoSize; /*default monospace font size*/
  67617.     short itlbPrefFond; /*preferred FOND ID*/
  67618.     short itlbPrefSize; /*preferred font size*/
  67619.     short itlbSmallFond; /*default small FOND ID*/
  67620.     short itlbSmallSize; /*default small font size*/
  67621.     short itlbSysFond; /*default system FOND ID*/
  67622.     short itlbSysSize; /*default system font size*/
  67623.     short itlbAppFond; /*default application FOND ID*/
  67624.     short itlbAppSize; /*default application font size*/
  67625.     short itlbHelpFond; /*default Help Mgr FOND ID*/
  67626.     short itlbHelpSize; /*default Help Mgr font size*/
  67627. };
  67628.  
  67629. typedef struct ItlbExtRecord ItlbExtRecord;
  67630. æC 
  67631.  
  67632. æKY MachineLocation
  67633. æFc Script.h
  67634. æT struct
  67635. æD struct MachineLocation {
  67636.     Fract latitude;
  67637.     Fract longitude;
  67638.     union{
  67639.     char dlsDelta; /*signed byte; daylight savings delta*/
  67640.     long gmtDelta; /*must mask - see documentation*/
  67641.     }gmtFlags;
  67642. };
  67643.  
  67644. typedef struct MachineLocation MachineLocation;
  67645. typedef short String2DateStatus;
  67646. typedef short TokenType;
  67647. typedef TokenType DelimType[2];
  67648. typedef TokenType CommentType[4];
  67649.  
  67650. æC 
  67651.  
  67652. æKY TokenRec
  67653. TokenRecPtr
  67654. æFc Script.h
  67655. æT struct
  67656. æD struct TokenRec {
  67657.     TokenType theToken;
  67658.     Ptr position; /*pointer into original Source*/
  67659.     long length; /*length of text in original source*/
  67660.     StringPtr stringPosition; /*Pascal/C string copy of identifier*/
  67661. };
  67662.  
  67663. typedef struct TokenRec TokenRec;
  67664. typedef TokenRec *TokenRecPtr;
  67665.  
  67666. æC 
  67667.  
  67668. æKY TokenBlock
  67669. TokenBlockPtr
  67670. æFc Script.h
  67671. æT struct
  67672. æD struct TokenBlock {
  67673.     Ptr source; /*pointer to stream of characters*/
  67674.     long sourceLength; /*length of source stream*/
  67675.     Ptr tokenList; /*pointer to array of tokens*/
  67676.     long tokenLength; /*maximum length of TokenList*/
  67677.     long tokenCount; /*number tokens generated by tokenizer*/
  67678.     Ptr stringList; /*pointer to stream of identifiers*/
  67679.     long stringLength; /*length of string list*/
  67680.     long stringCount; /*number of bytes currently used*/
  67681.     Boolean doString; /*make strings & put into StringLIst*/
  67682.     Boolean doAppend; /*append to TokenList rather than replace*/
  67683.     Boolean doAlphanumeric; /*identifiers may include numeric*/
  67684.     Boolean doNest; /*do comments nest?*/
  67685.     TokenType leftDelims[2];
  67686.     TokenType rightDelims[2];
  67687.     TokenType leftComment[4];
  67688.     TokenType rightComment[4];
  67689.     TokenType escapeCode; /*escape symbol code*/
  67690.     TokenType decimalCode;
  67691.     Handle itlResource; /*ptr to itl4 resource of current script*/
  67692.     long reserved[8]; /*must be zero!*/
  67693. };
  67694.  
  67695. typedef struct TokenBlock TokenBlock;
  67696. typedef TokenBlock *TokenBlockPtr;
  67697.  
  67698. æC 
  67699.  
  67700. æKY UntokenTable
  67701. UntokenTablePtr
  67702. UntokenTableHandle
  67703. æFc Script.h
  67704. æT struct
  67705. æD struct UntokenTable {
  67706.     short len;
  67707.     short lastToken;
  67708.     short index[256]; /*index table; last = lastToken*/
  67709. };
  67710.  
  67711. typedef struct UntokenTable UntokenTable;
  67712. typedef UntokenTable *UntokenTablePtr, **UntokenTableHandle;
  67713.  
  67714. æC 
  67715.  
  67716. æKY DateCacheRecord
  67717. DateCachePtr
  67718. æFc Script.h
  67719. æT struct
  67720. æD struct DateCacheRecord {
  67721.     short hidden[256]; /*only for temporary use*/
  67722. };
  67723.  
  67724. typedef struct DateCacheRecord DateCacheRecord;
  67725. typedef DateCacheRecord *DateCachePtr;
  67726.  
  67727. typedef comp LongDateTime;
  67728.  
  67729. æC 
  67730.  
  67731. æKY LongDateCvt
  67732. æFc Script.h
  67733. æT struct
  67734. æD union LongDateCvt {
  67735.     comp c;
  67736.     struct {
  67737.     long lHigh;
  67738.     long lLow;
  67739.     } hl;
  67740. };
  67741.  
  67742. typedef union LongDateCvt LongDateCvt;
  67743.  
  67744. æC 
  67745.  
  67746. æKY LongDateRec
  67747. æFc Script.h
  67748. æT struct
  67749. æD union LongDateRec {
  67750.     struct {
  67751.     short era;
  67752.     short year;
  67753.     short month;
  67754.     short day;
  67755.     short hour;
  67756.     short minute;
  67757.     short second;
  67758.     short dayOfWeek;
  67759.     short dayOfYear;
  67760.     short weekOfYear;
  67761.     short pm;
  67762.     short res1;
  67763.     short res2;
  67764.     short res3;
  67765.     } ld;
  67766.     short list[14]; /*Index by LongDateField!*/
  67767.     struct {
  67768.     short eraAlt;
  67769.     DateTimeRec oldDate;
  67770.     } od;
  67771. };
  67772.  
  67773. typedef union LongDateRec LongDateRec;
  67774.  
  67775. typedef char DateDelta;
  67776.  
  67777. æC 
  67778.  
  67779. æKY TogglePB
  67780. æFc Script.h
  67781. æT struct
  67782. æD struct TogglePB {
  67783.     long togFlags; /*caller normally sets low word to dateStdMask=$7F*/
  67784.     ResType amChars; /*from intl0*/
  67785.     ResType pmChars; /*from intl0*/
  67786.     long reserved[4];
  67787. };
  67788.  
  67789. typedef struct TogglePB TogglePB;
  67790. typedef short FormatOrder[1];
  67791. typedef FormatOrder *FormatOrderPtr;
  67792. typedef short FormatStatus;
  67793.  
  67794. æC 
  67795.  
  67796. æKY WideChar
  67797. æFc Script.h
  67798. æT struct
  67799. æD union WideChar {
  67800.     char a[2]; /*0 is the high order character*/
  67801.     short b;
  67802. };
  67803.  
  67804. typedef union WideChar WideChar;
  67805.  
  67806. æC 
  67807.  
  67808. æKY WideCharArr
  67809. æFc Script.h
  67810. æT struct
  67811. æD struct WideCharArr {
  67812.     short size;
  67813.     WideChar data[10];
  67814. };
  67815.  
  67816. typedef struct WideCharArr WideCharArr;
  67817. æC 
  67818.  
  67819. æKY NumFormatString
  67820. æFc Script.h
  67821. æT struct
  67822. æD struct NumFormatString {
  67823.     char fLength;
  67824.     char fVersion;
  67825.     char data[254]; /*private data*/
  67826. };
  67827.  
  67828. typedef struct NumFormatString NumFormatString;
  67829. æC 
  67830.  
  67831. æKY Itl4Rec
  67832. Itl4Ptr
  67833. Itl4Handle
  67834. æFc Script.h
  67835. æT struct
  67836. æD struct Itl4Rec {
  67837.     short flags;
  67838.     long resourceType;
  67839.     short resourceNum;
  67840.     short version;
  67841.     long resHeader1;
  67842.     long resHeader2;
  67843.     short numTables; /*one-based*/
  67844.     long mapOffset; /*offsets are from record start*/
  67845.     long strOffset;
  67846.     long fetchOffset;
  67847.     long unTokenOffset;
  67848.     long defPartsOffset;
  67849.     long resOffset6;
  67850.     long resOffset7;
  67851.     long resOffset8;
  67852. };
  67853.  
  67854. typedef struct Itl4Rec Itl4Rec;
  67855. typedef Itl4Rec *Itl4Ptr, **Itl4Handle;
  67856.  
  67857. æC 
  67858. _______________________________________________________________________________
  67859.  
  67860. »'Itl4' RESOURCE
  67861. _______________________________________________________________________________
  67862.  
  67863. There is a new international resource, 'itl4', which contains information used by
  67864. several of the 2.0 routines and must be localized for each script (including Roman).
  67865.  
  67866. In C:
  67867.  
  67868.   struct Itl4Rec {
  67869.           short    flags;
  67870.           long     resourceType;
  67871.           short    resourceNum;
  67872.           short    version;
  67873.           long     resHeader1;
  67874.           long     resHeader2;
  67875.           short    numTables;            /*one-based*/
  67876.           long     mapOffset;            /*offsets are from record start*/
  67877.           long     strOffset;
  67878.           long     fetchOffset;
  67879.           long     unTokenOffset;
  67880.           long     defPartsOffset;
  67881.           long     resOffset6;
  67882.           long     resOffset7;
  67883.           long     resOffset8;
  67884.   };
  67885.  
  67886.   #ifndef __cplusplus
  67887.   typedef struct Itl4Rec Itl4Rec;
  67888.   #endif
  67889.  
  67890.   typedef Itl4Rec *Itl4Ptr, **Itl4Handle;
  67891.  
  67892. _______________________________________________________________________________
  67893.  
  67894. æKY NItl4Rec
  67895. NItl4Ptr
  67896. NItl4Handle
  67897. æFc Script.h
  67898. æT struct
  67899. æD struct NItl4Rec {
  67900.     INTEGER flags;
  67901.     long resourceType;
  67902.     short resourceNum;
  67903.     short version;
  67904.     long resHeader1;
  67905.     long resHeader2;
  67906.     short numTables; /*one-based*/
  67907.     long mapOffset; /*offsets are from record start*/
  67908.     long strOffset;
  67909.     long fetchOffset;
  67910.     long unTokenOffset;
  67911.     long defPartsOffset;
  67912.     long truncMarkOffset;
  67913.     long resOffset7;
  67914.     long resOffset8;
  67915.     short resLength1;
  67916.     short resLength2;
  67917.     short resLength3;
  67918.     short unTokenLength;
  67919.     short defPartsLength;
  67920.     short resLength6;
  67921.     short resLength7;
  67922.     short resLength8;
  67923. };
  67924.  
  67925. typedef struct NItl4Rec NItl4Rec;
  67926. typedef NItl4Rec *NItl4Ptr, **NItl4Handle;
  67927.  
  67928. æC 
  67929.  
  67930. æKY NumberParts
  67931. NumberPartsPtr
  67932. æFc Script.h
  67933. æT struct
  67934. æD struct NumberParts {
  67935.     short version;
  67936.     WideChar data[31]; /*index by [tokLeftQuote..tokMaxSymbols]*/
  67937.     WideCharArr pePlus;
  67938.     WideCharArr peMinus;
  67939.     WideCharArr peMinusPlus;
  67940.     WideCharArr altNumTable;
  67941.     char reserved[20];
  67942. };
  67943.  
  67944. typedef struct NumberParts NumberParts;
  67945. typedef NumberParts *NumberPartsPtr;
  67946.  
  67947. æC 
  67948. This new Control Panel module on the utilities disk allows the user to set the latitude,
  67949. longitude, and time zone.  The values are stored in parameter RAM on the host machine.
  67950.  (See the Map cdev documentation for more details).
  67951.  
  67952. •••Refer to Figure 13.•••
  67953.  
  67954. Figure 13–Map
  67955.  
  67956. The new number routines supplement SANE, allowing applications to display formatted
  67957. numbers in the manner of Microsoft Excel or Fourth Dimension, and to read both formatted
  67958. and simple numbers.  The formatting strings allow natural display and entry of numbers
  67959. and editing of format strings even though the original numbers and the format strings
  67960. were entered in a language other than that of the final user.
  67961.  
  67962. Number parsing is based on a NumberParts table that describes the essentials of
  67963. numeric display for a particular language, including such components as thousands
  67964. separator, decimal point, scientific notation, forced zeroes in the absence of significant
  67965. digits, etc.  A default NumberParts table for each locale’s system resides in the
  67966. 'itl4' resource for that system.
  67967.  
  67968. _______________________________________________________________________________
  67969.  
  67970. »NumberParts
  67971.  
  67972. In C:
  67973.  
  67974.   struct NumberParts {
  67975.           short       version;
  67976.           WideChar    data[31];  /*index by [tokLeftQuote..tokMaxSymbols]*/
  67977.           WideCharArr pePlus;
  67978.           WideCharArr peMinus;
  67979.           WideCharArr peMinusPlus;
  67980.           WideCharArr altNumTable;
  67981.           char        reserved[20];
  67982.   };
  67983.  
  67984. Here is an example of how to access the 'itl4' default NumberParts table:
  67985.  
  67986. In C:
  67987.  
  67988.   DefaultParts(NumberParts *x)
  67989.   {
  67990.       Itl4Handle itl4;
  67991.  
  67992.       itl4 = (Itl4Handle)IUGetIntl(4);
  67993.  
  67994.       if ( itl4 ) {
  67995.           *x = *((NumberPartsPtr)( (char *)(*itl4) +
  67996.                 ((*itl4)->defPartsOffset ) ) );
  67997.           return(1);
  67998.       }
  67999.       return(0);
  68000.   }
  68001.  
  68002. The user provides a format descriptor string very similar to Fourth Dimension’s. 
  68003. This format string is translated by Str2Format in a canonical format which is transportable
  68004. between different languages such as French, English, and Japanese.  The canonical
  68005. format is stored in a record called NumFormatString.  This
  68006. record’s structure is as follows:
  68007.  
  68008. In C:
  68009.  
  68010.   struct NumFormatString {
  68011.           char  fLength;
  68012.           char  fVersion;
  68013.           char  data[254];     /*private data*/
  68014.   };
  68015.  
  68016. The format descriptor string may be broken into as many as three parts: positive,
  68017. negative, and zero.  For example, the number 3456.713 used with the canonical format
  68018. produced from “#,###.#;(#,###.#)” will produce the string representation “3,456.7” in
  68019. the United States.  In Switzerland the same canonical format would be displayed as
  68020. “#.###,#;(#.###,#),” and the number displayed with this format would be “3.456,7.”
  68021.  
  68022. The number formats include the following features (the defaults for the U.S. are
  68023. listed following):
  68024.  
  68025. Separators:
  68026.  
  68027.     decimal separator (.), thousands separator (,)
  68028.  
  68029.     Example:    format string: ###,###.0##,###
  68030.     1           —>    1.0
  68031.     1234        —>    1,234.0
  68032.     3.141592    —>    3.141,592
  68033.  
  68034. Digits:
  68035.  
  68036.     zero digit (0), skipping digit (#), padding digit (^), padding value (NBSP)
  68037.  
  68038.     Example:    format string: ###;(000);^^^
  68039.     1           —>    1
  68040.    -1           —>    (001)
  68041.     0           —>    0
  68042.  
  68043.     The number format routines always fill in digits from the right or
  68044.     from the left of the decimal point.
  68045.  
  68046.     Example:    format string: ###‘foo’###
  68047.     123foo456   —>    123foo456
  68048.     22foo44     —>    2foo244
  68049.     123foo      —>    123
  68050.  
  68051.     Example:    format string: 0.###‘foo’###
  68052.     0.foo123    —>    0.123
  68053.     0.1foo456   —>    0.145foo6
  68054.     0.1456      —>    0.145foo6
  68055.  
  68056.     Formats using zero and skipping digit characters do not allow extension
  68057.     beyond the minimum number of digits specified to the right or left of
  68058.     the decimal place.  For example: users must provide the desired maximum
  68059.     digits on the left: e.g., #,###,### instead of #,###.  X2FormStr will
  68060.     return a result of formatOverflow when the number contains more digits
  68061.     to the left of the decimal point than specified in the format string.
  68062.     Input values with more digits to the right of the decimal point than
  68063.     there are digits allowed in the format string will be rounded on output.
  68064.  
  68065.     Example:    format string: ###.###
  68066.     1234.56789  —>    formatOverflow on output
  68067.     1.234999    —>    1.235
  68068.  
  68069. Control:
  68070.  
  68071.     left quote (‘), right quote (’), escape quote (\), sign separator (;)
  68072.  
  68073.     Example:    format string: ###‘CR’;###‘DB’;‘\’zero\‘’
  68074.     1           —>    1CR
  68075.    -1           —>    1DB
  68076.     0           —>    ‘zero’
  68077.  
  68078. Marks:
  68079.  
  68080.  plus (+), minus (-), percent (%), positive exponent (E+),
  68081.  negative exponent (E-), mixed exponent (E)
  68082.  
  68083.     Example:    format string: ##%
  68084.     0.1         —>    10%
  68085.  
  68086.     There is a limitation creating format strings with exponential notation:
  68087.     the user must  always place zero leaders immediately after the exponent
  68088.     marks and skipping digits before, when more than one digit must be
  68089.     represented between the exponent and the decimal point.
  68090.  
  68091.     Example:    format string: ##.####E+0
  68092.     1.23E+3     —>    1.23E+3
  68093.  
  68094.     The sign of exponents must be made explicit in the format string by using
  68095.     ePlus (E+) or eMinus (E-) format.  eMinusPlus notation (E) is only used
  68096.     in the input number string to specify a positive exponent when the sign
  68097.     of the format string exponent is negative.
  68098.  
  68099.     format        +    exponent sign        -
  68100.     ePlus        ePlus(E+)        eMinus(E-)
  68101.     eMinus       eMinusPlus(E)    eMinus(E-)
  68102.  
  68103.     Use ePlus notation in the format string to specify negatively or
  68104.     positively signed exponents in the input number string:
  68105.  
  68106.     Example:    ePlus format string: #.#E+#
  68107.     1.2E-3      —>    1.2E-3
  68108.     1.2E+3      —>    1.2E+3
  68109.  
  68110.     Example:    eMinus format string: #.#E-#
  68111.     1.2E-3      —>    1.2E-3
  68112.     1.2E3       —>    1.2E3     (i.e., 1200)
  68113.  
  68114. Literals:
  68115.  
  68116.     unquoted literals ([]$:(){}), literals requiring quotes (ABC...)
  68117.  
  68118.     Example:    format string: [###‘ Million ’###‘ Thousand ’###]
  68119.     300         —>    [300]
  68120.     3000000     —>    [3 Million 000 Thousand 000]
  68121.  
  68122. A typical scenario consists of the application reading the default NumberParts table
  68123. from 'itl4'.  One provides a format definition string, such as the string “#.###,#;(#.###,#)”
  68124. of the above example, as a template for whatever field one is currently working in. 
  68125. The application submits that string to Str2Format, which  returns a canonical format
  68126. string corresponding to the user’s input.  This canonical format, rather than the raw
  68127. format definition string, is stored in the document.  The program can convert the
  68128. canonical format back to a user-editable string using the Format2Str routine.
  68129.  
  68130. When a number is to be displayed, the application passes the number and canonical
  68131. format to FormatX2Str to produce a formatted number that the application then displays
  68132. in that field.  If the user types a string into the field, then FormatStr2X can be
  68133. used with the canonical format for the field to read formatted numbers.  That is, the
  68134. user can type “(3.678,9)” and have the number interpreted correctly.
  68135.  
  68136. æKY FVector
  68137. æFc Script.h
  68138. æT struct
  68139. æD struct FVector {
  68140.     short start;
  68141.     short length;
  68142. };
  68143.  
  68144. typedef struct FVector FVector;
  68145. typedef FVector TripleInt[3]; /* index by [fPositive..fZero] */
  68146.  
  68147. æC 
  68148.  
  68149. æKY ScriptRunStatus
  68150. æFc Script.h
  68151. æT struct
  68152. æD struct ScriptRunStatus {
  68153.     short script;
  68154.     short variant;
  68155. };
  68156.  
  68157. typedef struct ScriptRunStatus ScriptRunStatus;
  68158. æC 
  68159.  
  68160. æKY FontScript
  68161. æFc Script.h
  68162. æT Function
  68163. æTN A8B5
  68164. æD pascal short FontScript(void)
  68165.     = {0x2F3C,0x8200,0x0000,0xA8B5}; 
  68166. æDT short myVariable = FontScript()(void);
  68167. æMM
  68168. æRI V-314
  68169. æC  
  68170. FontScript returns the script code for the font script.  The font script is determined
  68171. by the font of the current grafPort.
  68172.  
  68173. æKY IntlScript
  68174. æFc Script.h
  68175. æT Function
  68176. æTN A8B5
  68177. æD pascal short IntlScript(void)
  68178.     = {0x2F3C,0x8200,0x0002,0xA8B5}; 
  68179. æDT short myVariable = IntlScript()(void);
  68180. æMM
  68181. æRI V-314
  68182. æC  
  68183. IntlScript returns the script code for the International Utilities script.  Like the
  68184. font script, the International Utilities script is determined by the font of the
  68185. current grafPort.  If the Script Manager global IntlForce is off, then IntlScript is
  68186. the same as the font script; if IntlForce is on, IntlScript is the system script. 
  68187. For further information, see the International Utilities Package chapter in this
  68188. volume.
  68189.  
  68190. æKY KeyScript
  68191. æFc Script.h
  68192. æT Function
  68193. æTN A8B5
  68194. æD pascal void KeyScript(short code)
  68195.     = {0x2F3C,0x8002,0x0004,0xA8B5}; 
  68196. æDT KeyScript((short) code);
  68197. æMM
  68198. æRI V-314
  68199. æC 
  68200. KeyScript is used to set the keyboard script.  This routine also changes the keyboard
  68201. layout to that of the new keyboard script and draws the script icon for the new
  68202. keyboard script in the upper-right corner of the menu bar.
  68203.  
  68204. Warning:  Applications can also change the keyboard script without changing
  68205.           the keyboard layout or the script icon in the menu bar, by calling
  68206.           the SetEnvirons routine with the smKeyScript verb. However, this
  68207.           method should only be used to momentarily change the keyboard script
  68208.           to perform a special operation.  Changing the keyboard script without
  68209.           changing the keyboard layout violates the user interface paradigm and
  68210.           will cause problems for other Script Manager routines.
  68211.  
  68212. æKY Font2Script
  68213. æFc Script.h
  68214. æT Function
  68215. æTN A8B5
  68216. æD pascal short Font2Script(short fontNumber)
  68217.     = {0x2F3C,0x8202,0x0006,0xA8B5}; 
  68218. æDT short myVariable = Font2Script((short) fontNumber);
  68219. æMM
  68220. æRI V-315
  68221. æC 
  68222. Font2Script translates a font identification number into a script code.  This routine
  68223. is useful for determining to which script a particular font belongs and which fonts
  68224. are usable under a particular script.
  68225.  
  68226. æKY GetEnvirons
  68227. æFc Script.h
  68228. æT Function
  68229. æTN A8B5
  68230. æD pascal long GetEnvirons(short verb)
  68231.     = {0x2F3C,0x8402,0x0008,0xA8B5}; 
  68232. æDT long myVariable = GetEnvirons((short) verb);
  68233. æRT 243
  68234. æRI V-313
  68235. æC  
  68236. •••Refer to Technical Note #243:•••
  68237.  
  68238. GetEnvirons is used to retrieve the values of the global Script Manager variables and
  68239. routine vectors.  The following predefined constants are available for the verb
  68240. argument:
  68241.  
  68242.   Constant       Value    Meaning
  68243.  
  68244.   smVersion      0        Environment version
  68245.   smMunged       2        Globals changed count
  68246.   smEnabled      4        Environment enabled flag
  68247.   smBiDirect     6        Set if scripts of different directions
  68248.                           are installed together
  68249.   smFontForce    8        Force font flag
  68250.   smIntlForce    10       Force international utilities flag
  68251.   smForced       12       Current script forced to system script
  68252.   smDefault      14       Current script defaulted to Roman script
  68253.   smPrint        16       Printer action routine
  68254.   smSysScript    18       System script
  68255.   smLastScript   20       Last keyboard script
  68256.   smKeyScript    22       Keyboard script
  68257.   smSysRef       24       System folder reference number
  68258.   smKeyCache     26       Keyboard table cache pointer
  68259.   smKeySwap      28       Swapping table pointer
  68260.   smGenFlags     30       General Flags
  68261.   smOverride     32       Script Override flags
  68262.   smCharPortion  34       Ch vs Sp Extra proportion, 4.12 fixed
  68263.  
  68264. This routine returns 0 if the verb is not recognized.
  68265.  
  68266. æKY SetEnvirons
  68267. æFc Script.h
  68268. æT Function
  68269. æTN A8B5
  68270. æD pascal OSErr SetEnvirons(short verb,long param)
  68271.     = {0x2F3C,0x8206,0x000A,0xA8B5}; 
  68272. æDT OSErr myVariable = SetEnvirons((short) verb,(long) param);
  68273. æRI V-314
  68274. æC  
  68275. SetEnvirons is the opposite of GetEnvirons.  It is used to change the global Script
  68276. Interface System variables and routine vectors; it uses the same verbs as GetEnvirons.
  68277.  The value smVerbNotFound is returned if the verb is not recognized.  Otherwise, the
  68278. function result will be noErr.
  68279.  
  68280. It is a good idea to first retrieve the original value of the global variable that
  68281. you want to change, using GetEnvirons.  The original value can then be restored with
  68282. a second call to SetEnvirons as soon as possible.
  68283.  
  68284. æKY GetScript
  68285. æFc Script.h
  68286. æT Function
  68287. æTN A8B5
  68288. æD pascal long GetScript(short script,short verb)
  68289.     = {0x2F3C,0x8404,0x000C,0xA8B5}; 
  68290. æDT long myVariable = GetScript((short) script,(short) verb);
  68291. æRT 243
  68292. æRI V-312
  68293. æC  
  68294. •••Refer to Technical Note #243:•••
  68295.  
  68296. GetScript is used to retrieve the values of the local script variables and routine
  68297. vectors.  The following predefined constants are available for the verb parameter:
  68298.  
  68299.   Constant           Value    Meaning
  68300.  
  68301.   smScriptVersion    0        Software version
  68302.   smScriptMunged     2        Script entry changed count
  68303.   smScriptEnabled    4        Script enabled flag
  68304.   smScriptRight      6        Right-to-left flag
  68305.   smScriptJust       8        Justification flag
  68306.   smScriptRedraw     10       Word redraw flag
  68307.   smScriptSysFond    12       Preferred system font
  68308.   smScriptAppFond    14       Preferred application font
  68309.   smScriptNumber     16       Script 'itl0' ID, from dictionary
  68310.   smScriptDate       18       Script 'itl1' ID, from dictionary
  68311.   smScriptSort       20       Script 'itl2' ID, from dictionary
  68312.   smScriptFlags      22       Script Flags Word
  68313.   smScriptToken      24       'itl4' ID number
  68314.   smScriptRsvd3      26       Reserved
  68315.   smScriptLang       28       Script’s language code
  68316.   smScriptNumDate    30       Number/Date Representation codes
  68317.   smScriptKeys       32       Script 'KCHR' ID, from dictionary
  68318.   smScriptIcon       34       Script 'SICN' ID, from dictionary
  68319.   smScriptPrint      36       Script printer action routine
  68320.   smScriptTrap       38       Trap entry pointer
  68321.   smScriptCreator    40       Script file creator
  68322.   smScriptFile       42       Script file name
  68323.   smScriptName       44       Script name
  68324.  
  68325. Verb values unique to a script are defined by the applicable Script Interface System.
  68326.  GetScript returns 0 if the verb value is not recognized or if the specified script
  68327. is not installed.
  68328.  
  68329. æKY SetScript
  68330. æFc Script.h
  68331. æT Function
  68332. æTN A8B5
  68333. æD pascal OSErr SetScript(short script,short verb,long param)
  68334.     = {0x2F3C,0x8208,0x000E,0xA8B5}; 
  68335. æDT OSErr myVariable = SetScript((short) script,(short) verb,(long) param);
  68336. æRI V-313
  68337. æC 
  68338. SetScript is the opposite of GetScript.  It is used to change the local script variables
  68339. and routine vectors and uses the same verb values as GetScript.  The value smVerbNotFound
  68340. is returned if the verb value is not recognized or the script specified is not installed.
  68341.  Otherwise, the function result will be noErr.  It is a good idea to first retrieve
  68342. the original value of the global variable that you want to change, using GetScript. 
  68343. The original value can then be restored with a second call to SetScript as soon as
  68344. possible.
  68345.  
  68346. æKY CharByte
  68347. æFc Script.h
  68348. æT Function
  68349. æTN A8B5
  68350. æD pascal short CharByte(Ptr textBuf,short textOffset)
  68351.     = {0x2F3C,0x8206,0x0010,0xA8B5}; 
  68352. æDT short myVariable = CharByte((Ptr) textBuf,(short) textOffset);
  68353. æRI V-306
  68354. æC  
  68355. CharByte is used to check the character type of the byte at the given offset
  68356. (using an offset of zero for the first character in the buffer). It can return the
  68357. following values:
  68358.  
  68359.   Value    Meaning
  68360.  
  68361.    –1      First byte of a multibyte character
  68362.     0      Single-byte character
  68363.     1      Last byte of multibyte character
  68364.     2      Middle byte of multibyte character
  68365.  
  68366. æKY CharType
  68367. æFc Script.h
  68368. æT Function
  68369. æTN A8B5
  68370. æD pascal short CharType(Ptr textBuf,short textOffset)
  68371.     = {0x2F3C,0x8206,0x0012,0xA8B5}; 
  68372. æDT short myVariable = CharType((Ptr) textBuf,(short) textOffset);
  68373. æRI V-306
  68374. æC 
  68375. CharType is an extension of CharByte which returns more information about the given
  68376. byte.
  68377.  
  68378. Note:  If the byte indicated by the offset is not the last or the only byte
  68379.        of a character, the offset should be incremented until the CharType
  68380.        call is made for the lowest-order byte.
  68381.  
  68382. The format of the return value is an integer with the following structure:
  68383.  
  68384.   Bits    Contents
  68385.  
  68386.   0–3     Character type
  68387.   4–7     Reserved
  68388.   8–11    Character class (subset of type)
  68389.   12      Reserved
  68390.   13      Direction
  68391.   14      Character case
  68392.   15      Character size
  68393.  
  68394. Each Script Interface System defines constants for the different types of characters.
  68395. The following predefined constants are available to help you access the CharType
  68396. return value for the Roman script:
  68397.  
  68398. CONST
  68399.  
  68400.   { CharType character types }
  68401.  
  68402.   smCharPunct    = 0;
  68403.   smCharAscii    = 1;
  68404.   smCharEuro     = 7;
  68405.  
  68406.   { CharType character classes }
  68407.  
  68408.   smPunctNormal  = $0000;
  68409.   smPunctNumber  = $0100;
  68410.   smPunctSymbol  = $0200;
  68411.   smPunctBlank   = $0300;
  68412.  
  68413.   { CharType directions }
  68414.  
  68415.   smCharLeft     = $0000;
  68416.   smCharRight    = $2000;
  68417.  
  68418.   { CharType character case }
  68419.  
  68420.   smCharLower    = $0000;
  68421.   smCharUpper    = $4000;
  68422.  
  68423.   { CharType character size (1 or 2 byte) }
  68424.  
  68425.   smChar1byte    = $0000;
  68426.   smChar2byte    = $8000;
  68427.  
  68428. For example, if the character indicated were an uppercase “A” (single-byte), then the
  68429. value of the result would be smCharAscii + smCharUpper.  Blank characters are indicated
  68430. by a type smCharPunct and a class smCharBlank.
  68431.  
  68432. æKY Pixel2Char
  68433. æFc Script.h
  68434. æT Function
  68435. æTN A8B5
  68436. æD pascal short Pixel2Char(Ptr textBuf,short textLen,short slop,short pixelWidth,
  68437.     Boolean *leadingEdge)
  68438.     = {0x2F3C,0x820E,0x0014,0xA8B5}; 
  68439. æDT short myVariable = Pixel2Char((Ptr) textBuf,(short) textLen,(short) slop,(short) pixelWidth,(
  68440.     Boolean) * leadingEdge);
  68441. æMM
  68442. æRT 207
  68443. æRI V-307
  68444. æC  
  68445. Pixel2Char should be used to find the nearest character offset within a text buffer
  68446. corresponding to a given pixel width.  It returns the offset of the character that
  68447. pixelWidth is closest to.  It is the inverse of the Char2Pixel routine.
  68448.  
  68449. The leftSide flag is set if the pixel width falls within the left side of a character.
  68450. This flag can be used for word selection, and for positioning the cursor correctly at
  68451. the end of lines.  For example, during word selection if the character offset is at
  68452. the end of a word and the leftSide flag is on, then the double click was actually on
  68453. the following character, and the preceding word should not be selected.
  68454.  
  68455. The slop argument is used for justified text. It specifies how many extra pixels must
  68456. be added to the length of the string.  If the text is not justified, pass a slop
  68457. value of zero.
  68458.  
  68459. æKY Char2Pixel
  68460. æFc Script.h
  68461. æT Function
  68462. æTN A8B5
  68463. æD pascal short Char2Pixel(Ptr textBuf,short textLen,short slop,short offset,
  68464.     short direction)
  68465.     = {0x2F3C,0x820C,0x0016,0xA8B5}; 
  68466. æDT short myVariable = Char2Pixel((Ptr) textBuf,(short) textLen,(short) slop,(short) offset,()
  68467.     short direction);
  68468. æMM
  68469. æRT 207
  68470. æRI V-308
  68471. æC  
  68472. Char2Pixel is the inverse of Pixel2Char ; it should be used to find the screen position
  68473. of carets and selection points, given the text and length.  For left-to-right scripts
  68474. (including kanji), this routine works the same way as TextWidth.  For other scripts,
  68475. it works differently.  The parameters are the same as in Pixel2Char, except for the
  68476. direction.
  68477.  
  68478. The direction argument indicates whether Char2Pixel is being called to determine
  68479. where the caret should appear or to find the endpoints for highlighting. For unidirectional
  68480. scripts such as Roman, it should have the value 1.  The following predefined constants
  68481. are available for specifying the direction:
  68482.  
  68483. CONST
  68484.   smLeftCaret   =  0;    {place caret for left block}
  68485.   smRightCaret  = -1;    {place caret for right block}
  68486.   smHilite      =  1;    {direction is TESysJust}
  68487.  
  68488. Like Pixel2Char, this routine can handle fully justified text.  If the text is not
  68489. justified, pass a slop value of zero.
  68490.  
  68491. Although Char2Pixel uses TextWidth (with Roman script), the arguments passed are not
  68492. the same. TextWidth, for ease of calling from Pascal, takes a byteCount argument
  68493. which is redundant. The length and offset for Char2Pixel are not equivalent; the
  68494. routine needs the context of the complete text in order to determine the correct
  68495. value. For example, if myPtr is a pointer to the text
  68496. ‘abcdefghi’, with the cursor between the ‘d’ and the ‘e’ (and no justification), the
  68497. call would be
  68498.  
  68499.   pixelWidth := Char2Pixel(myPtr, 9, 0, 4, 1);
  68500.  
  68501. When Char2Pixel is used to blink the insertion, the direction parameter to Char2Pixel
  68502. should depend on the keyboard script. The call can look like this:
  68503.  
  68504.   keyDirection := GetScript(GetEnvirons(smKeyScript),smScriptRight);
  68505.   pixelWidth := Char2Pixel(myPtr, 9, 0, 4, keyDirection);
  68506.  
  68507. However, the keyboard script may change between drawing and erasing the insertion
  68508. point. An application should remember the position where it drew the cursor, then
  68509. erase (invert) at that position again. This can be done by remembering the  keyDirection,
  68510. the pixel width, or even the whole rectangle. For example, if the application remembers
  68511. the keyDirection by declaring it as a global variable, code like this could be used:
  68512.  
  68513.   drawingInsertion := true;    {when window is activated}
  68514.   .
  68515.   .
  68516.   .
  68517.   {to blink the insertion point}
  68518.   IF drawingInsertion THEN
  68519.     BEGIN{drawing}
  68520.       keyDirection := GetScript(GetEnvirons(smKeyScript),smScriptRight);
  68521.       pixelWidth := Char2Pixel(myPtr, myLength, mySlop, keyDirection);
  68522.       {Get the vertical position for the insertion point, then invert }
  68523.       { the appropriate rectangle}
  68524.     END
  68525.   ELSE
  68526.     BEGIN {erasing}
  68527.       pixelWidth := Char2Pixel(myPtr, myLength, mySlop, keyDirection);
  68528.       {Get the vertical position for the insertion point, then invert }
  68529.       { the appropriate rectangle}
  68530.     END; {blinking}
  68531.   drawingInsertion := not drawingInsertion;
  68532.  
  68533. æKY Transliterate
  68534. æFc Script.h
  68535. æT Function
  68536. æTN A8B5
  68537. æD pascal OSErr Transliterate(Handle srcHandle,Handle dstHandle,short target,
  68538.     long srcMask)
  68539.     = {0x2F3C,0x820E,0x0018,0xA8B5}; 
  68540. æDT OSErr myVariable = Transliterate((Handle) srcHandle,(Handle) dstHandle,(short) target,()
  68541.     long srcMask);
  68542. æMM
  68543. æRI V-311
  68544. æC  
  68545. Transliterate converts the given text to the closest possible approximation in a
  68546. different script or type of character. It is the caller’s responsibility to provide
  68547. storage and dispose of it. The srcMask indicates which character types
  68548. (scripts) in the source are to be converted. For example, Japanese text may contain
  68549. Roman, hiragana, katakana, and kanji characters. The source mask could be used to
  68550. limit transliteration to hiragana characters only.
  68551.  
  68552. The target value specifies what the text is to be transliterated into.  The low byte
  68553. of the target is the format to convert to.  A value of –1 means the system script.
  68554. The high byte contains modifiers, which depend on the specific script number.  The
  68555. following predefined constants are available to help you specify target values:
  68556.  
  68557.   Constant        Value    Meaning
  68558.  
  68559.   smTransAscii    0        Target is Roman script
  68560.   smTransNative   1        Target is non-Roman script
  68561.   smTransCase     2        Switch case for any target
  68562.   smTransLower    16384    Target becomes lowercase
  68563.   smTransUpper    32768    Target becomes uppercase
  68564.   smMaskAscii     1        Convert only Roman script
  68565.   smMaskNative    2        Convert only non-Roman script
  68566.   smMaskAll      –1        Convert all text
  68567.  
  68568. The result is 0 for noErr or –1 for transliteration not available.
  68569.  
  68570. Transliteration is performed on a “best effort” basis: typically it will be designed
  68571. to give a unique transliteration into the non-Roman script.  This may not be the most
  68572. phonetic or natural transcription, since those transcriptions are usually ambiguous
  68573. (for example, in certain transcriptions “th” may refer to the sound in the, the sound
  68574. in thick, or the sounds in boathouse).
  68575.  
  68576. On Roman systems, this routine is typically used to change case.  For example, to
  68577. convert all the characters in a block of text to single-byte Roman
  68578. (uppercase), the value of srcMask would be smMaskAll, and target would be smTransUpper+smTransAscii.
  68579.  Each of the Script Interface Systems defines additional target constants to be used
  68580. during transliteration.
  68581.  
  68582. Here are some examples of the effects of transliteration:
  68583.  
  68584.   to uppercase    ----->    TO UPPERCASE
  68585.   TO LOWERCASE    ----->    to lowercase
  68586.  
  68587. æKY FindWord
  68588. æFc Script.h
  68589. æT Function
  68590. æTN A8B5
  68591. æD pascal void FindWord(Ptr textPtr,short textLength,short offset,Boolean leadingEdge,
  68592.     BreakTablePtr breaks,OffsetTable offsets)
  68593.     = {0x2F3C,0x8012,0x001A,0xA8B5}; 
  68594. æDT FindWord((Ptr) textPtr,(short) textLength,(short) offset,(Boolean) leadingEdge,()
  68595.     BreakTablePtr breaks,(OffsetTable) offsets);
  68596. æMM
  68597. æRT 182
  68598. æRI V-309
  68599. æC 
  68600. FindWord takes a text string, passed in the textPtr and textLength parameters, and a
  68601. position in the string, passed as an offset.   The leftSide flag has the same meaning
  68602. here as in the Pixel2Char routine.  FindWord returns two offsets in the offset table
  68603. which specify the boundaries of the word selected by the offset and leftSide.   For
  68604. example,  if the text “This is it” were passed with an offset and leftSide that
  68605. selected the first word, the offset pair returned would be (0,4).
  68606.  
  68607. FindWord uses a break table—a list of word-division templates—to determine the boundaries
  68608. of a word.  If the breaks parameter is NIL, the default word-selection break table
  68609. for the current script is used.  If it is POINTER(–1), then the default word-wrapping
  68610. break table is used. If the breaks parameter has another value, it should point to a
  68611. valid break table, which will be used in place of the default table. For information
  68612. about constructing alternate break tables, contact Developer Technical Support.
  68613.  
  68614. Word-selection break tables are used to find boundaries of words for word selection,
  68615. dragging, spelling checking, and so on.  Word-wrapping break tables are used to
  68616. distinguish words for finding the widths of lines for wrapping. Word selection generally
  68617. makes finer distinctions than word wrapping.  For example, the default word-selection
  68618. break table for Roman script yields three words in the string  (here): (, here, and).  
  68619. For word wrapping, on the other hand, this string is considered to be one word.
  68620.  
  68621. æKY HiliteText
  68622. æFc Script.h
  68623. æT Function
  68624. æTN A8B5
  68625. æD pascal void HiliteText(Ptr textPtr,short textLength,short firstOffset,short secondOffset,
  68626.     OffsetTable offsets)
  68627.     = {0x2F3C,0x800E,0x001C,0xA8B5}; 
  68628. æDT HiliteText((Ptr) textPtr,(short) textLength,(short) firstOffset,(short) secondOffset,()
  68629.     OffsetTable offsets);
  68630. æMM
  68631. æRI V-310
  68632. æC  
  68633. HiliteText is used to find the characters between two offsets that should be highlighted.
  68634.  The offsets are passed in firstOffset and secondOffset, and returned in offsetTable.
  68635.  
  68636. The offsetTable can be thought of as a set of three offset pairs.  If the two offsets
  68637. in any pair are equal, the pair is empty and can be skipped.  Otherwise the pair
  68638. identifies a run of characters. Char2Pixel can be used to convert the offsets into
  68639. pixel widths, if necessary.
  68640.  
  68641. The offsetTable requires three offset pairs because in bidirectional scripts a single
  68642. selection may comprise up to three physically discontinuous segments. In the Arabic
  68643. script, for example, Arabic words are written right-to-left while English words in
  68644. the same line are written left-to-right. Thus the selection of a section of Arabic
  68645. containing an English word can appear as shown in Figure 3.
  68646.  
  68647. •••Refer to Figure 3.•••
  68648.  
  68649. Figure 3–Example of Bidirectional Selection
  68650.  
  68651. HiLiteText returns the specific regions to be highlighted in this case as an offset
  68652. table.
  68653.  
  68654. æKY DrawJust
  68655. æFc Script.h
  68656. æT Function
  68657. æTN A8B5
  68658. æD pascal void DrawJust(Ptr textPtr,short textLength,short slop)
  68659.     = {0x2F3C,0x8008,0x001E,0xA8B5}; 
  68660. æDT DrawJust((Ptr) textPtr,(short) textLength,(short) slop);
  68661. æMM
  68662. æRI V-310
  68663. æC 
  68664. DrawJust is similar to the QuickDraw DrawText routine.  It draws the given text at
  68665. the current pen location in the current font, style, and size.  The slop parameter
  68666. indicates how many extra pixels are to be added to the width of the string when it is
  68667. drawn.  This is useful for justifying text.
  68668.  
  68669. æKY MeasureJust
  68670. æFc Script.h
  68671. æT Function
  68672. æTN A8B5
  68673. æD pascal void MeasureJust(Ptr textPtr,short textLength,short slop,Ptr charLocs)
  68674.     = {0x2F3C,0x800C,0x0020,0xA8B5}; 
  68675. æDT MeasureJust((Ptr) textPtr,(short) textLength,(short) slop,(Ptr) charLocs);
  68676. æMM
  68677. æRI V-311
  68678. æC  
  68679. MeasureJust is similar to the QuickDraw MeasureText routine.  The charLocs parameter
  68680. should point to an array of textLength+1 integers; MeasureJust will fill it with the
  68681. TextWidths of the first textLength characters of the text pointed to by textPtr.  The
  68682. first entry in the array will return the width of zero characters, the second the
  68683. width of the first character, the third the width of the first and second characters,
  68684. and so forth.
  68685.  
  68686. æKY ParseTable
  68687. æFc Script.h
  68688. æT Function
  68689. æTN A8B5
  68690. æD 
  68691. pascal Boolean ParseTable(CharByteTable table)
  68692.     = {0x2F3C,0x8204,0x0022,0xA8B5}; 
  68693. æDT Boolean myVariable = ParseTable((CharByteTable) table);
  68694. æC     Double-byte characters have distinctive high (first) bytes, which allows them to be
  68695. distinguished from single-byte characters.  The ParseTable routine can be used to 
  68696. traverse double-byte text quickly.  It does this by filling a table of bytes with 
  68697. values which indicate the extra number of bytes taken by a given character.  
  68698.  
  68699.     This array can then be used instead of making function calls on each 
  68700. byte.  As with the other script-specific routine calls, the values in the table will
  68701. vary with the script of the current font in thePort, so you must make sure to set 
  68702. the font correctly.
  68703.  
  68704.     An entry in the table is set to 0 for a single-byte character and 1 for the first
  68705. byte of a double-byte character.  (With a single-byte script, the entries are all 
  68706. zero.)
  68707.  
  68708.     The return value from the routine will always be true.  This routine has always 
  68709. been present in the Script Manager, but was not documented until now.  Also note that 
  68710. script systems will never require more than two bytes per character, so you can safely 
  68711. assume that there are only single-byte and double-byte characters.
  68712.  
  68713. For example, in the following code the reference to tablePtr[myChar] is functionally 
  68714. equivalent to a use of _CharByte, but does not involve a trap call.
  68715.  
  68716. In Pascal:
  68717.  
  68718. Var
  68719.   myChar:  Integer;
  68720.   i, max:  Integer;
  68721.   tablePtr:  CharByteTable;
  68722.   s:    String [255];
  68723.   parseResult:  Boolean;
  68724.  
  68725. Begin
  68726.   parseResult := ParseTable(tablePtr);
  68727.   i := 1;
  68728.   max := length (s);
  68729.   While i <= max do Begin
  68730.     myChar := ord(s[i]);                    {get byte}
  68731.     i := i + 1;                             {skip to start of next}
  68732.     if (tablePtr[myChar] <> 0) then Begin   {if double-byte}
  68733.       myChar := myChar * $100 + ord(s[i]);  {include next byte}
  68734.       i := i + 1;                           {skip to start of next}
  68735.     End;
  68736.         {do something with myChar}
  68737.   End;
  68738. End;
  68739.  
  68740. In C:
  68741.  
  68742. short    mychar;
  68743. CharByteTable  table;
  68744. char    *s = "Test String";
  68745. Boolean  parseResult;
  68746.  
  68747. {
  68748.   parseResult = ParseTable(table);
  68749.   
  68750.   while (*s) {
  68751.     mychar = *s;        /*get the first byte*/
  68752.     s++;
  68753.     if (table[*s] <> 0)
  68754.       mychar = (mychar * 0x100) + *s;
  68755.     /* Do something with mychar */
  68756.   }
  68757. }
  68758.  
  68759. Remember that the CharByteTable is specific to the script.  There could be two 
  68760. or three scripts installed that are double-byte and have different 
  68761. CharByteTable arrays.
  68762.  
  68763. æKY GetDefFontSize
  68764. æFc Script.h
  68765. æT Function
  68766. æD pascal short GetDefFontSize(void)
  68767.     = {0x3EB8,0x0BA8,0x6604,0x3EBC,0x000C}; 
  68768. æDT short myVariable = GetDefFontSize()(void);
  68769. æRI V-315
  68770. æC 
  68771. GetDefFontSize fetches the size of the current default font.  This routine is in the
  68772. Pascal interface, not in ROM; it cannot be used with the 64K ROM.
  68773.  
  68774. æKY GetSysFont
  68775. æFc Script.h
  68776. æT Function
  68777. æD pascal short GetSysFont(void)
  68778.     = {0x3EB8,0x0BA6}; 
  68779. æDT short myVariable = GetSysFont()(void);
  68780. æRI V-315
  68781. æC 
  68782. GetSysFont fetches the identification number of the current system font.  This routine
  68783. is in the Pascal interface, not in ROM; it cannot be used with the 64K ROM.
  68784.  
  68785. æKY GetAppFont
  68786. æFc Script.h
  68787. æT Function
  68788. æD pascal short GetAppFont(void)
  68789.     = {0x3EB8,0x0984}; 
  68790. æDT short myVariable = GetAppFont()(void);
  68791. æRI V-315
  68792. æC  
  68793. GetAppFont fetches the identification number of the current application font.  This
  68794. routine is in the Pascal interface, not in ROM.
  68795.  
  68796. æKY GetMBarHeight
  68797. æFc Script.h
  68798. æT Function
  68799. æD pascal short GetMBarHeight(void)
  68800.     = {0x3EB8,0x0BAA}; 
  68801. æDT short myVariable = GetMBarHeight()(void);
  68802. æRI V-315
  68803. æC  
  68804. GetMBarHeight fetches the height of the menu bar as required to hold menu titles in
  68805. its current font.  This routine is in the Pascal interface, not in ROM; it cannot be
  68806. used with the 64K ROM.
  68807.  
  68808. æKY GetSysJust
  68809. æFc Script.h
  68810. æT Function
  68811. æD pascal short GetSysJust(void)
  68812.     = {0x3EB8,0x0BAC}; 
  68813. æDT short myVariable = GetSysJust()(void);
  68814. æRI V-315
  68815. æC  
  68816. GetSysJust returns the value of a global variable that represents the direction in
  68817. which lines written in the system script are justified: 0 for left justification (the
  68818. default case) or –1 for right justification.  This routine is in the Pascal interface,
  68819. not in ROM; it cannot be used with the 64K ROM.
  68820.  
  68821. æKY SetSysJust
  68822. æFc Script.h
  68823. æT Function
  68824. æD pascal void SetSysJust(short newJust)
  68825.     = {0x31DF,0x0BAC}; 
  68826. æDT SetSysJust((short) newJust);
  68827. æRI V-316
  68828. æC 
  68829. GetSysJust sets a global variable that represents the direction in which lines written
  68830. in the system script are justified: 0 for left justification (the default case) or –1
  68831. for right justification.  This routine is in the Pascal interface, not in ROM; it
  68832. cannot be used with the 64K ROM.
  68833.  
  68834. æKY ReadLocation
  68835. æFc Script.h
  68836. æT Function
  68837. æD pascal void ReadLocation(MachineLocation *loc)
  68838.     = {0x205F,0x203C,0x000C,0x00E4,0xA051}; 
  68839. æDT ReadLocation((MachineLocation *) loc);
  68840. æC 
  68841. In C:
  68842.  
  68843.   pascal void ReadLocation(MachineLocation *loc);
  68844.   pascal void WriteLocation(const MachineLocation *loc);
  68845.  
  68846. These routines allow the programmer to access the stored geographic location of the
  68847. Macintosh and time zone information from parameter RAM.  For example, the time zone
  68848. information can be used to derive the absolute time (GMT) that a document or mail
  68849. message was created.  With this information, when the document is received across
  68850. time zones, the creation date and time are correct.  Otherwise, documents can appear
  68851. to be created after” they are read (e.g., I can create a message in Tokyo on Tuesday
  68852. and send it to Cupertino, where it is received and read on Monday).  Geographic
  68853. information can also be used by applications which require it.
  68854.  
  68855. If the MachineLocation has never been set, then it should be <0,0,0>.  The top byte
  68856. of the gmtDelta should be masked off and preserved when writing: it is reserved for
  68857. future extension.  The gmtDelta is in seconds east of GMT: e.g., San Francisco is at
  68858. minus 28,800 seconds (8 hours * 3600 seconds per hour).  The latitude and longitude
  68859. are in fractions of a great circle, giving them accuracy to within less than a foot,
  68860. which should be sufficient for most purposes.  For example, Fract values of 1.0 =
  68861. 90°, -1.0 = -90°, -2.0 = -180°.
  68862.  
  68863. In C:
  68864.  
  68865.   struct MachineLocation {
  68866.           Fract latitude;
  68867.           Fract longitude;
  68868.           union{
  68869.               char   dlsDelta;    /*signed byte; daylight savings delta*/
  68870.               long   gmtDelta;    /*must mask - see documentation*/
  68871.           }   gmtFlags;
  68872. };
  68873.  
  68874. The gmtDelta is really a three-byte value, so the user must take care to get and set
  68875. it properly as in the following code examples:
  68876.  
  68877. In C:
  68878.  
  68879.   long GetGmtDelta(MachineLocation myLocation)
  68880.   {
  68881.       long    internalGMTDelta;
  68882.  
  68883.       internalGMTDelta = myLocation.gmtDelta & 0x00ffffff;
  68884.  
  68885.       if ( (internalGMTDelta >> 23) & 1 ) // need to sign extend
  68886.             internalGmtDelta = internalGmtDelta | 0xff000000;
  68887.   
  68888.       return(internalGmtDelta);
  68889.   }
  68890.  
  68891.   void SetGmtDelta(MachineLocation *myLocation, long myGmtDelta)
  68892.   {
  68893.       char tempSignedByte;
  68894.  
  68895.       tempSignedByte = myLocation->dlsDelta;
  68896.       myLocation->gmtDelta = myGmtDelta;
  68897.       myLocation->dlsDelta = tempSignedByte;
  68898.   }
  68899.  
  68900. •••Refer to Figure 12.•••
  68901.  
  68902. Figure 12–Locations
  68903.  
  68904. æKY WriteLocation
  68905. æFc Script.h
  68906. æT Function
  68907. æD pascal void WriteLocation(const MachineLocation *loc)
  68908.     = {0x205F,0x203C,0x000C,0x00E4,0xA052}; 
  68909. æDT WriteLocation((const MachineLocation *) loc);
  68910. æC 
  68911. In C:
  68912.  
  68913.   pascal void ReadLocation(MachineLocation *loc);
  68914.   pascal void WriteLocation(const MachineLocation *loc);
  68915.  
  68916. These routines allow the programmer to access the stored geographic location of the
  68917. Macintosh and time zone information from parameter RAM.  For example, the time zone
  68918. information can be used to derive the absolute time (GMT) that a document or mail
  68919. message was created.  With this information, when the document is received across
  68920. time zones, the creation date and time are correct.  Otherwise, documents can appear
  68921. to be created after” they are read (e.g., I can create a message in Tokyo on Tuesday
  68922. and send it to Cupertino, where it is received and read on Monday).  Geographic
  68923. information can also be used by applications which require it.
  68924.  
  68925. If the MachineLocation has never been set, then it should be <0,0,0>.  The top byte
  68926. of the gmtDelta should be masked off and preserved when writing: it is reserved for
  68927. future extension.  The gmtDelta is in seconds east of GMT: e.g., San Francisco is at
  68928. minus 28,800 seconds (8 hours * 3600 seconds per hour).  The latitude and longitude
  68929. are in fractions of a great circle, giving them accuracy to within less than a foot,
  68930. which should be sufficient for most purposes.  For example, Fract values of 1.0 =
  68931. 90°, -1.0 = -90°, -2.0 = -180°.
  68932.  
  68933. In C:
  68934.  
  68935.   struct MachineLocation {
  68936.           Fract latitude;
  68937.           Fract longitude;
  68938.           union{
  68939.               char   dlsDelta;    /*signed byte; daylight savings delta*/
  68940.               long   gmtDelta;    /*must mask - see documentation*/
  68941.           }   gmtFlags;
  68942. };
  68943.  
  68944. The gmtDelta is really a three-byte value, so the user must take care to get and set
  68945. it properly as in the following code examples:
  68946.  
  68947. In C:
  68948.  
  68949.   long GetGmtDelta(MachineLocation myLocation)
  68950.   {
  68951.       long    internalGMTDelta;
  68952.  
  68953.       internalGMTDelta = myLocation.gmtDelta & 0x00ffffff;
  68954.  
  68955.       if ( (internalGMTDelta >> 23) & 1 ) // need to sign extend
  68956.             internalGmtDelta = internalGmtDelta | 0xff000000;
  68957.   
  68958.       return(internalGmtDelta);
  68959.   }
  68960.  
  68961.   void SetGmtDelta(MachineLocation *myLocation, long myGmtDelta)
  68962.   {
  68963.       char tempSignedByte;
  68964.  
  68965.       tempSignedByte = myLocation->dlsDelta;
  68966.       myLocation->gmtDelta = myGmtDelta;
  68967.       myLocation->dlsDelta = tempSignedByte;
  68968.   }
  68969.  
  68970. •••Refer to Figure 12.•••
  68971.  
  68972. Figure 12–Locations
  68973.  
  68974. æKY UprText
  68975. æFc Script.h
  68976. æT Function
  68977. æD 
  68978. pascal void UprText(Ptr textPtr,short len)
  68979.     = {0x301F,0x205F,0xA054}; 
  68980. æDT 
  68981. UprText((Ptr) textPtr,(short) len);
  68982. æC 
  68983. In C:
  68984.  
  68985.   pascal void UprText(Ptr textPtr,short len);
  68986.   pascal void LwrText(Ptr textPtr,short len);
  68987.  
  68988. UprText provides a Pascal interface to the _UprString assembly routine, which will
  68989. uppercase text up to 32K in length.  The LwrText routine provides the corresponding
  68990. lowercase routine.  Both of these routines will not change the number or position of
  68991. characters in a string, but are faster and simpler than the Transliterate routine.
  68992.  
  68993. æKY LwrText
  68994. æFc Script.h
  68995. æT Function
  68996. æD pascal void LwrText(Ptr textPtr,short len)
  68997.     = {0x301F,0x205F,0xA056}; 
  68998. æDT LwrText((Ptr) textPtr,(short) len);
  68999. æC 
  69000. In C:
  69001.  
  69002.   pascal void UprText(Ptr textPtr,short len);
  69003.   pascal void LwrText(Ptr textPtr,short len);
  69004.  
  69005. UprText provides a Pascal interface to the _UprString assembly routine, which will
  69006. uppercase text up to 32K in length.  The LwrText routine provides the corresponding
  69007. lowercase routine.  Both of these routines will not change the number or position of
  69008. characters in a string, but are faster and simpler than the Transliterate routine.
  69009.  
  69010. æKY LowerText
  69011. æFc Script.h
  69012. æT Function
  69013. æD 
  69014. pascal void LowerText(Ptr textPtr,short len)
  69015.     = {0x301F,0x205F,0xA056}; 
  69016. æDT 
  69017. LowerText((Ptr) textPtr,(short) len);
  69018. æC 
  69019.  
  69020. æKY StripText
  69021. æFc Script.h
  69022. æT Function
  69023. æD pascal void StripText(Ptr textPtr,short len)
  69024.     = {0x301F,0x205F,0xA256}; 
  69025. æDT StripText((Ptr) textPtr,(short) len);
  69026. æC 
  69027.  
  69028. æKY UpperText
  69029. æFc Script.h
  69030. æT Function
  69031. æD 
  69032. pascal void UpperText(Ptr textPtr,short len)
  69033.     = {0x301F,0x205F,0xA456}; 
  69034. æDT 
  69035. UpperText((Ptr) textPtr,(short) len);
  69036. æC 
  69037.  
  69038. æKY StripUpperText
  69039. æFc Script.h
  69040. æT Function
  69041. æD 
  69042. pascal void StripUpperText(Ptr textPtr,short len)
  69043.     = {0x301F,0x205F,0xA656}; 
  69044. æDT 
  69045. StripUpperText((Ptr) textPtr,(short) len);
  69046. æC 
  69047.  
  69048. æKY StyledLineBreak
  69049. æFc Script.h
  69050. æT Function
  69051. æD pascal StyledLineBreakCode StyledLineBreak(Ptr textPtr,long textLen,long textStart,
  69052.     long textEnd,long flags,Fixed *textWidth,long *textOffset)
  69053.     = {0x2F3C,0x821C,0xFFFE,0xA8B5}; 
  69054. æDT StyledLineBreakCode myVariable = StyledLineBreak((Ptr) textPtr,(long) textLen,(long) textStart,()
  69055.     long textEnd,(long) flags,(Fixed *) textWidth,(long *) textOffset);
  69056. æC 
  69057. In C:
  69058.  
  69059.   pascal StyledLineBreakCode StyledLineBreak(Ptr textPtr,long textLen,
  69060.                                              long textStart,long textEnd,
  69061.                                              long flags,Fixed *textWidth,
  69062.                                              long *textOffset);
  69063.  
  69064.   enum {smBreakWord,smBreakChar,smBreakOverflow};
  69065.   typedef unsigned char StyledLineBreakCode;
  69066.  
  69067. This routine breaks a line on a word boundary.  The user will loop through a sequence
  69068. of format runs, resetting the textPtr and textLen each time the script changes; and
  69069. resetting the textStart and textEnd for each format run.  The textWidth will automatically
  69070. be decremented by StyledLineBreak.
  69071.  
  69072. TextPtr points to the start of the text, textLen indicates the maximum length of the
  69073. text, and the textWidth parameter indicates the maximum pixel width of the rectangle
  69074. used to display the text starting at the textStart and ending at the textEnd.  The
  69075. flags parameter is reserved for future expansion and must be zero.
  69076.  
  69077. •••Refer to Figure 7.•••
  69078.  
  69079. Figure 7–StyledLineBreak
  69080.  
  69081. On input, a non-zero textOffset indicates whether this is the first format run
  69082. (possibly forcing a character break rather than a word break:  if textOffset is
  69083. non-zero, at least one character will be returned if the line is not empty).  On
  69084. output it is the number of bytes from textPtr up to the point where the line should
  69085. be broken.  If the passed textWidth extended beyond the end of the text
  69086. (i.e., is larger than the width from textoffset to textLen), then the width of the
  69087. text is subtracted from the textWidth and the result returned in the textWidth parameter.
  69088.  This can be used for the next format run.
  69089.  
  69090. The routine result indicates whether the routine broke on a word boundary, character
  69091. boundary, or the width extended beyond the edge of the text.
  69092.  
  69093. When used with single-format text, the textStart can be zero, and the textEnd identical
  69094. with the textLen.  With multi-format text, the interval between textStart and textEnd
  69095. specifies a format run.  The interval between textPtr and textLen specifies a script
  69096. run (a contiguous sequence of text where the script of each of the format runs is the
  69097. same).  Note that the format runs in StyledLineBreak must be traversed in back-end
  69098. storage order, not display order
  69099. (see GetFormatOrder).
  69100.  
  69101. In other words, if the current format run is included in a contiguous sequence of
  69102. other format runs of the same script, then the textPtr should point to the start of
  69103. the first format run of the same script, while the textLen should include the last
  69104. format run of the same script.  This is so that word boundaries can extend across
  69105. format runs; they will never extend across script runs.
  69106.  
  69107. Although the offsets are in longint values and widths in fixed for future extensions,
  69108. in the current version the longint values should be restricted to the integer range,
  69109. and only the integer portion of the widths will be used.
  69110.  
  69111. æKY GetFormatOrder
  69112. æFc Script.h
  69113. æT Function
  69114. æD pascal void GetFormatOrder(FormatOrderPtr ordering,short firstFormat,short lastFormat,
  69115.     Boolean lineRight,Ptr rlDirProc,Ptr dirParam)
  69116.     = {0x2F3C,0x8012,0xFFFC,0xA8B5}; 
  69117. æDT GetFormatOrder((FormatOrderPtr) ordering,(short) firstFormat,(short) lastFormat,()
  69118.     Boolean lineRight,(Ptr) rlDirProc,(Ptr) dirParam);
  69119. æC 
  69120. In C:
  69121.  
  69122.   typedef short       FormatOrder[1];
  69123.   typedef FormatOrder *FormatOrderPtr;
  69124.  
  69125.   pascal void GetFormatOrder(FormatOrderPtr ordering,short firstFormat,
  69126.                              short lastFormat, Boolean lineRight,
  69127.                              Ptr rlDirProc, Ptr dirParam);
  69128.  
  69129. This routine orders the text properly for display of bidirectional format runs.  Word
  69130. processing programs that use this procedure for multi-font text can be independent of
  69131. script text-ordering in a line (e.g., Hebrew or Arabic right-left text).  The ordering
  69132. points to an array of integers, with (lastFormat – firstFormat + 1) entries.  The
  69133. GetFormatOrder routine retrieves the direction of each format by calling the direction
  69134. procedure, RLDirProc, which has the following format:
  69135.  
  69136. In C:
  69137.  
  69138.   pascal Boolean MyRLDirProc(short theFormat, Ptr dirParam);
  69139.  
  69140. The RLDirProc is called with the values from firstFormat to lastFormat to determine
  69141. the directions of each of the format runs.  It returns true for
  69142. right-left text direction, otherwise false.  The parameter dirParam is available to
  69143. provide other necessary information for the direction procedure
  69144. (i.e., style number, pointer to style array, etc).
  69145.  
  69146. GetFormatOrder returns a permuted list of the numbers from firstFormat to lastFormat.
  69147.  This permuted list can be used to draw or measure the text.
  69148. (For more detail, see the Script Manager developers’ packet).  The lineRight parameter
  69149. is true if the text is right-left orientation, otherwise false.
  69150.  
  69151. The array Ordering is created and filled by your application.  The first element in
  69152. the array should correspond to the parameter firstFormat, and the last element should
  69153. correspond to lastFormat.  GetFormatOrder loops through this array and passes each
  69154. element in the array back to the RLDirProc function.  Since you fill the ordering
  69155. array and you write the RLDirProc, you should obviously store format runs in a way
  69156. that makes the GetFormatOrder routine useable.
  69157.  
  69158. One obvious way to do this would be to declare a record type for format runs that
  69159. allowed you to save things like font style, font ID, script number, and so on.  You
  69160. then could store these records in an array.  When the time came to call GetFormatOrder,
  69161. you would simply fill the Ordering array with the indexes that you used to access
  69162. your array of format run records.  GetFormatOrder would return an array which described
  69163. the correct drawing order for your format runs.
  69164.  
  69165. Consider this example.  Let uppercase letters stand for format runs that are left to
  69166. right, and lowercase letters stand for right-left format runs.  For example, there
  69167. are two format runs in the following line.
  69168.  
  69169.   1  2
  69170.   ABCfed
  69171.  
  69172. With left-right line direction, the text should appear on the screen as:
  69173.  
  69174.   1  2
  69175.   ABCdef
  69176.  
  69177. With right-left line direction, the text should appear on the screen as:
  69178.  
  69179.   2  1
  69180.   fedABC
  69181.  
  69182. GetFormatOrder is used to tell you what order the format runs should be drawn in
  69183. based on line direction for a particular line of text.
  69184.  
  69185. •••Refer to Figure 6.•••
  69186.  
  69187. Figure 6–GetFormatOrder
  69188.  
  69189. For example, In C:
  69190.  
  69191.   GetFormatOrder(myOrdering,firstFormat,lastFormat,(Boolean)GetSysJust(),
  69192.                 (Ptr)MyRLDirProc,nil);
  69193.   for ( i = 0, i <= (lastFormat-firstFormat), i++)
  69194.       /* set up style stuff */
  69195.       switch what {
  69196.           case drawing:
  69197.                 DrawText(textStartPtr,formatStart,formatLength);
  69198.                 break;
  69199.           case measuring:
  69200.                 TextWidth(textStartPtr,formatStart,formatLength);
  69201.                 break;
  69202.           default:
  69203.                 break;
  69204.       }
  69205.  
  69206. æKY IntlTokenize
  69207. æFc Script.h
  69208. æT Function
  69209. æD pascal TokenResults IntlTokenize(TokenBlockPtr tokenParam)
  69210.     = {0x2F3C,0x8204,0xFFFA,0xA8B5}; 
  69211. æDT TokenResults myVariable = IntlTokenize((TokenBlockPtr) tokenParam);
  69212. æC 
  69213. In C:
  69214.  
  69215.   pascal TokenResults IntlTokenize(TokenBlockPtr tokenParam);
  69216.  
  69217. The IntlTokenize routine is intended for use in macro expressions and similar programming
  69218. constructs intended for general users.  It allows the program to recognize variables,
  69219. symbols and quoted literals without depending on the particular natural language
  69220. (e.g., English vs. Japanese).
  69221.  
  69222. The routine is a mildly programmable regular expression recognizer for parsing text
  69223. into tokens.  The single parameter is a parameter block describing the text to be
  69224. tokenized, the destination of the token stream, the 'itl4' resource handle, and the
  69225. various programmable options.  IntlTokenize will return a list of tokens found in the
  69226. text.
  69227.  
  69228. In C:
  69229.  
  69230.   struct TokenBlock {
  69231.         Ptr        source;          /*pointer to stream of characters*/
  69232.         long       sourceLength;    /*length of source stream*/
  69233.         Ptr        tokenList;       /*pointer to array of tokens*/
  69234.         long       tokenLength;     /*maximum length of TokenList*/
  69235.         long       tokenCount;      /*number tokens generated by tokenizer*/
  69236.         Ptr        stringList;      /*pointer to stream of identifiers*/
  69237.         long       stringLength;    /*length of string list*/
  69238.         long       stringCount;     /*number of bytes currently used*/
  69239.         Boolean    doString;        /*make strings & put into StringLIst*/
  69240.         Boolean    doAppend;        /*append to TokenList rather than replace*/
  69241.         Boolean    doAlphanumeric;  /*identifiers may include numeric*/
  69242.         Boolean    doNest;          /*do comments nest?*/
  69243.         TokenType  leftDelims[2];
  69244.         TokenType  rightDelims[2];
  69245.         TokenType  leftComment[4];
  69246.         TokenType  rightComment[4];
  69247.         TokenType  escapeCode;      /*escape symbol code*/
  69248.         TokenType  decimalCode;
  69249.         Handle     itlResource;     /*ptr to itl4 resource of current script*/
  69250.         long       reserved[8];     /*must be zero!*/
  69251.   };
  69252.  
  69253.   #ifndef __cplusplus
  69254.   typedef struct TokenBlock TokenBlock;
  69255.   #endif
  69256.  
  69257.   typedef TokenBlock *TokenBlockPtr;
  69258.  
  69259.   typedef short TokenType;
  69260.  
  69261.   struct TokenRec {
  69262.       TokenType theToken;
  69263.       Ptr       Position;             /*pointer into original Source*/
  69264.       long      length;               /*length of text in original source*/
  69265.       StringPtr stringPosition;       /*Pascal/C string copy of identifier*/
  69266.   };
  69267.  
  69268. For the TokenBlock record:
  69269.  
  69270. source          is a pointer to the beginning of a stream of characters
  69271.                 (not a Pascal string).
  69272.  
  69273. sourceLength    is the number of characters in the source stream.
  69274.  
  69275. tokenList       is a pointer to memory allocated by the application for the
  69276.                 token stream.  The tokenizer places the tokens it generates
  69277.                 at and after the address in tokenList.
  69278.  
  69279. tokenLength     is the number of tokens that will fit in the memory pointed
  69280.                 to by tokenList (not the number of bytes).
  69281.  
  69282. tokenCount      is the number of tokens that are currently occupying the space
  69283.                 pointed to by tokenList.  If the doAppend flag is true, then
  69284.                 tokenCount must be a correct number before calling the
  69285.                 tokenizer.  The tokenizer modifies this value to show how many
  69286.                 tokens are in the token stream after tokenizing.
  69287.  
  69288. stringList      is a pointer to memory allocated by the application for strings
  69289.                 that the tokenizer generates if the doString flag is true.  If
  69290.                 the flag is false, then stringList is ignored.
  69291.  
  69292. stringLength    is the number of bytes of memory allocated for stringList.
  69293.  
  69294. stringCount     is the number of bytes that are currently occupying the space
  69295.                 pointed to by stringList.  If the doAppend flag is true, then
  69296.                 stringCount must be a correct number before calling the
  69297.                 tokenizer.  The tokenizer modifies this value to show how many
  69298.                 bytes are in the string stream after tokenizing.
  69299.  
  69300. doString        is a boolean flag that instructs the tokenizer to create a
  69301.                 sequence of even-boundaried, null-terminated Pascal strings.
  69302.                 Each token generated by the tokenizer will have a string
  69303.                 created to represent it if the flag is true.  Each token
  69304.                 record contains the address of the string that represents it.
  69305.  
  69306. doAppend        is a boolean flag that instructs the tokenizer to append tokens
  69307.                 to the space pointed to by tokenList rather than replace
  69308.                 whatever is there.  tokenCount must correctly reflect the
  69309.                 number of tokens in the space pointed to by tokenList.
  69310.  
  69311. doAlphanumeric  is a boolean flag that, when true, states that numerics may
  69312.                 be mixed with alphabetics to create alphabetic tokens.
  69313.  
  69314. doNest          is a boolean flag that instructs the tokenizer to allow nested
  69315.                 comments of any depth.
  69316.  
  69317. leftDelims      is an array of two integers, each of which corresponds to the
  69318.                 class of the symbol that may be used as a left delimiter for a
  69319.                 quoted literal. Double quotes, for instance, is class
  69320.                 token2Quote.  If only one left delimiter is needed, the other
  69321.                 must be specified to be delimPad.
  69322.  
  69323. rightDelims     is an array of two integers, each of which corresponds to the
  69324.                 class of the symbol that may be used as the matching right
  69325.                 delimiter for the corresponding left delimiter in leftDelims.
  69326.  
  69327. leftComment     is an array of four integers.  Each successive pair of two
  69328.                 describes a pair of tokens that may be used as left delimiters
  69329.                 for comments.  These tokens are stored in reverse order.  The
  69330.                 tokens numbered zero and two are the second tokens of the two-
  69331.                 token sequences; the tokens numbered one and three are the
  69332.                 first tokens of the two-token sequences.
  69333.  
  69334.                 If only one token is needed for a delimiter, the second token
  69335.                 must be specified to be delimPad.  If only one delimiter is
  69336.                 needed, then both of the tokens allocated for the other symbol
  69337.                 must be delimPad.  The first token of a two-token sequence is
  69338.                 the higher position in the array.  For example, the two left
  69339.                 delimiters (* and { would be specified as
  69340.  
  69341.                   leftComment[0]:= tokenAsterisk;     (*asterisk*)
  69342.                   leftComment[1]:= tokenLeftParen;    (*left parenthesis*)
  69343.                   leftComment[2]:= delimPad ;         (*nothing*)
  69344.                   leftComment[3]:= tokenLeftCurly;    (*curly brace*)
  69345.  
  69346. rightComment    is an array of four integers with similar characteristics as
  69347.                 leftComment.  The positions in the array of the right
  69348.                 delimiters must be the same as their matching left delimiters.
  69349.  
  69350. escapeChar      is a single integer that is the class of the symbol that may be
  69351.                 used for an escape character.  The tokenizer considers the
  69352.                 escape character to be an escape character (as opposed to being
  69353.                 itself) only within quoted literals.
  69354.  
  69355.                 If backslash (\) is given as the escapeChar, then the tokenizer
  69356.                 would consider it an escape character in the following string:
  69357.  
  69358.                   "This is an escape\n"
  69359.  
  69360.                 It would not be considered an escape character in a non-quoted
  69361.                 string like the following:
  69362.  
  69363.                   This isn't an escape\n
  69364.  
  69365. decimalCode     is a single integer that is the tokenType that may be used for
  69366.                 a decimal point.  The tokenizer considers the decimal character
  69367.                 to be a decimal character (as opposed to being itself) only
  69368.                 when flanked by numeric or alternate numeric characters, or
  69369.                 when following them.  When the strings option is selected, the
  69370.                 decimal character will always be transliterated to an ASCII
  69371.                 period (and alternate numbers will be transliterated to ASCII
  69372.                 digits).
  69373.  
  69374. itlResource     is a handle to the 'itl4' resource of the script in current
  69375.                 use.  The application must load the 'itl4' resource and place
  69376.                 its handle here before calling the tokenizer.  Every time the
  69377.                 script of the text to be tokenized changes, the pointer to the
  69378.                 respective 'itl4' resource must be placed here.
  69379.  
  69380. reserved        locations must all be zeroed.
  69381.  
  69382. For the token record:
  69383.  
  69384. theToken        is the ordinal value of the token represented by the token
  69385.                 record.
  69386.  
  69387. position        points to the first character in the original text that
  69388.                 caused this particular token to be generated.
  69389.  
  69390. length          is the length in bytes of the original text corresponding
  69391.                 to this token.
  69392.  
  69393. stringPosition  points to a null-terminated, even-boundariedPascal string
  69394.                 that is the result of using the doString option.  If doString
  69395.                 is false then stringPosition is always set to NIL.
  69396.  
  69397. The available token types are:  whitespace, newline, alphabetic, numeric, decimal,
  69398. endOfStream, unknown, alternate numeric, alternate decimal, and a host of fixed token
  69399. symbols, such as ( # @ : := .
  69400.  
  69401. The tokenizer does not attempt to provide complete lexical analysis, but rather
  69402. offers a programmable “pre-lex” function whose output should then be processed by the
  69403. application at a lexical or syntactic level.
  69404.  
  69405. The programmable options include: whether to generate strings which correspond to the
  69406. text of each token; whether the current tokenize call is to append to, rather than
  69407. replace, the current token list; whether alphabetic tokens may have numerics within
  69408. them; whether comments may be nested; what the left and right delimiters for comments
  69409. are (up to two sets may be specified); what the left and right delimiters for quoted
  69410. literals are (up to two sets may be specified); what the escape character is; and
  69411. what the decimal point symbol is.
  69412.  
  69413. Some users may use two or more different scripts within a program.  However, each
  69414. script’s character stream must be passed separately to the tokenizer because different
  69415. resources must be passed to the tokenizer depending on the script of the text stream.
  69416.  Appending tokens to the token stream lets the application see the tokens generated
  69417. by the different scripts’ characters as a single token stream.  Restriction: users
  69418. may not change scripts within a comment or quoted literal because these syntactic
  69419. units must be complete within a single call to the tokenizer in order to avoid tokenizer
  69420. syntax errors.
  69421.  
  69422. The application may specify up to two pairs of delimiters each for both quoted literals
  69423. and comments.  Quoted literal delimiters consist of a single symbol, and comment
  69424. delimiters may be either one or two symbols (including newline for notations whose
  69425. comments automatically terminate at the end of lines).  The characters that compose
  69426. literals within quoted literals and comments are normally defined to have no syntactic
  69427. significance; however, the escape character within a quoted literal does signal that
  69428. the following character should not be treated as the right delimiter.  Each delimiter
  69429. is represented by a token, as is the literal between left and right delimiters.
  69430.  
  69431. If two different comment delimiters are specified by the application, then the doNest
  69432. flag always applies to both.  Comments may be nested if so specified by the doNest
  69433. flag with one restriction that must be strictly observed in order to prevent the
  69434. tokenizer from malfunctioning:  nesting is legal only if both the left and right
  69435. delimiters for the comment token are composed of two symbols each.  In this version,
  69436. there is limited support for nested comments.  When using this feature, test to
  69437. insure that it meets your requirements.
  69438.  
  69439. An escape character between left and right delimiters of a quoted literal signals
  69440. that the following character is not the right delimiter.  An escape character is not
  69441. specially recognized and has no significance outside of quoted literals.  When an
  69442. escape character is encountered, the portion of the literal before the escape is
  69443. placed into a single token, the escape character itself becomes a token, the character
  69444. following the escape becomes a token, and the portion of the literal following the
  69445. escape sequence becomes a token.
  69446.  
  69447. A sequence of whitespace characters becomes a single token.
  69448.  
  69449. Newline, or carriage return, becomes a single token.
  69450.  
  69451. A sequence of alphabetic characters becomes an alphabetic token.  If the doAlphanumeric
  69452. flag is set, then alphabetic characters include digits, but the first character must
  69453. be alphabetic.
  69454.  
  69455. A sequence of numeric characters becomes a numeric token.
  69456.  
  69457. A sequence of numeric characters followed by a decimal mark, and optionally followed
  69458. by more numeric characters, becomes a realNumber token.
  69459.  
  69460. Some scripts have not only “English” digits, but also their own numeral codes, which
  69461. of course will be unrecognizable to the typical application.  A sequence of alternate
  69462. digits becomes an alternate numeric token.  If the strings option is selected then
  69463. the digits will be transliterated to “English” digits.  This includes the realNumber
  69464. tokens, whose results become alternate real tokens.
  69465.  
  69466. The end of the character stream becomes a token.
  69467.  
  69468. A token record consists of a token code, a pointer into the source stream
  69469. (signifying the first character of the sequence that generated the token), the byte
  69470. length of the sequence of characters that generated the token, and space for a pointer
  69471. to a Pascal string, explained next.
  69472.  
  69473. The application may instruct the tokenizer to generate null-terminated, even-boundaried
  69474. Pascal strings corresponding to each token.  In this case, if the token is anything
  69475. but alphabetic or numeric then the text of the source stream is copied verbatim into
  69476. the Pascal string.  Otherwise, if the text in the source stream is Roman letters or
  69477. numbers then those characters are transliterated into Macintosh eight-bit ASCII and a
  69478. string is created from
  69479. the result, allowing users of other languages to transparently use their own script’s
  69480. numerals or Roman characters for numbers or keywords.  Non-Roman alphabetics are
  69481. copied verbatim.
  69482.  
  69483. Semantic attributes of byte codes vary from natural language to natural language.  As
  69484. an example, in the Macintosh character set code $81 is an Å, but in Kanji this code
  69485. is the first byte of many double-byte characters, some of which are alphabetic, some
  69486. numeric, and some symbols.  This information is retrieved from the 'itl4' resource,
  69487. which also contains a canonical string format for the fixed tokens, so that the
  69488. internal format of formulæ can be redisplayed in the original language.
  69489.  
  69490. 'itl4' also holds a string copy routine which converts the native text to the corresponding
  69491. English (except for alphanumerics).  As with the other international resources, the
  69492. choice of 'itl4' depends on the script interface system in use.
  69493.  
  69494. •••Refer to Figure 4.•••
  69495.  
  69496. Figure 4–IntlTokenize
  69497.  
  69498. The untokenTable in the 'itl4' resource contains standard representations for the
  69499. fixed tokens, and can be used to display the internal format.  An example of how a
  69500. user might access this table and use the token information follows:
  69501.  
  69502. In C:
  69503.  
  69504.   struct UntokenTable {
  69505.       short  len;
  69506.       short  lastToken;
  69507.       short  index[256];               /*index table; last = lastToken*/
  69508.   };
  69509.  
  69510.   #ifndef __cplusplus
  69511.   typedef struct UntokenTable UntokenTable;
  69512.   #endif
  69513.  
  69514.   typedef UntokenTable *UntokenTablePtr, **UntokenTableHandle;
  69515.  
  69516.   GetUntokenTable(UntokenTableHandle *x)
  69517.   {
  69518.     Itl4Handle       itl4;
  69519.     UntokenTablePtr  p;
  69520.  
  69521.     itl4 = (Itl4Handle)IUGetIntl(4);
  69522.  
  69523.     if (itl4) {
  69524.         HLock((Handle)itl4);
  69525.   
  69526.         P = (UntokenTablePtr)( (char *)(*itl4) + ( (*itl4)->unTokenOffset ) );
  69527.   
  69528.         *x = (UntokenTableHandle)NewHandle(p->len);
  69529.   
  69530.         if (x)
  69531.             BlockMove((Ptr)p,(Ptr)**x,p->len);
  69532.       
  69533.         HUnlock((Handle)itl4);
  69534.   
  69535.         return((short)*x);
  69536.     }
  69537.     else
  69538.         return(0);
  69539.   }
  69540.  
  69541.   if ( GetUntokenTable(myUntokenTable) )
  69542.       switch curtoken->theToken {
  69543.       /* ... */
  69544.       case tokenAlpha:
  69545.           AppendString(myvariable[i]);
  69546.           break;
  69547.       default:
  69548.           if (curtoken->theToken > lastToken)
  69549.               AppendString("?");
  69550.           else {
  69551.               Hlock((Handle)myUntokenTable);
  69552.               sptr = (char *)(*myUntokenTable) +
  69553.                      (*myUntokenTable)->index[curtoken->theToken];
  69554.               AppendString(sptr);
  69555.               HUnlock((Handle)myUntokenTable);
  69556.           }
  69557.           break;
  69558.   }
  69559.  
  69560. æKY InitDateCache
  69561. æFc Script.h
  69562. æT Function
  69563. æD pascal OSErr InitDateCache(DateCachePtr theCache)
  69564.     = {0x2F3C,0x8204,0xFFF8,0xA8B5}; 
  69565. æDT OSErr myVariable = InitDateCache((DateCachePtr) theCache);
  69566. æC 
  69567. In C:
  69568.  
  69569.   pascal OSErr InitDateCache(DateCachePtr theCache);
  69570.  
  69571. This routine must be called before using the String2Date or String2Time routines to
  69572. format the theCache record.  Allocation of this record is the responsibility of the
  69573. caller:  it can either be a local variable, a Ptr or a locked Handle.  By using this
  69574. cache, the performance of the String2Date and String2Time routines is improved.
  69575.  
  69576. In C:
  69577.  
  69578.   void MyRoutine()
  69579.   {
  69580.     DateCacheRecord    myCache;
  69581.  
  69582.     InitDateCache(&myCache);
  69583.     /* Now you can call String2Date or String2Time, Note that if you
  69584.        are doing this inside an application where global variables are
  69585.        allowed, you should probably make your Date cache a global and
  69586.        initialize it once when you initialize the Toolbox managers
  69587.     */
  69588.   }
  69589.  
  69590. æKY String2Date
  69591. æFc Script.h
  69592. æT Function
  69593. æD pascal String2DateStatus String2Date(Ptr textPtr,long textLen,DateCachePtr theCache,
  69594.     long *lengthUsed,LongDateRec *dateTime)
  69595.     = {0x2F3C,0x8214,0xFFF6,0xA8B5}; 
  69596. æDT String2DateStatus myVariable = String2Date((Ptr) textPtr,(long) textLen,(DateCachePtr) theCache,(
  69597.     long) * lengthUsed,(LongDateRec *) dateTime);
  69598. æC 
  69599. In C:
  69600.  
  69601.   pascal String2DateStatus String2Date(Ptr textPtr,long textLen,
  69602.                                        DateCachePtr theCache, long *lengthUsed,
  69603.                                        LongDateRec *dateTime);
  69604.  
  69605.   pascal String2DateStatus String2Time(Ptr textPtr,long textLen,
  69606.                                        DateCachePtr theCache, long *lengthUsed,
  69607.                                        LongDateRec *dateTime);
  69608.  
  69609. These routines expect a date and time at the beginning of the text.  They parse the
  69610. text, setting the lengthUsed to reflect the remainder of the text, and fill the
  69611. dateTime record.  They recognize all the strings that are produced by the international
  69612. date and time utilities, and others.  For example, they will recognize the following
  69613. dates: September 1, 1987; 1 Sept 1987; 1/9/1987; and 1 1987 sEpT.
  69614.  
  69615. If the value of the input year is less than 100, then it is added to 1900; if less
  69616. than 1000, then it is added to 1000 (the appropriate values are used from other
  69617. calendars, gotten from the base date: LongDateTime = 0).  Thus the dates 1/9/1987 and
  69618. 1/9/87 are equivalent.
  69619.  
  69620. The routines use the following grammar to interpret the date and time.  The relevant
  69621. fields of the international utilities resources are used for separators, month and
  69622. weekday names, and the ordering of the date elements.  The parsing is actually semantic-driven,
  69623. so finer distinctions are made than those represented in the syntax diagram.
  69624.  
  69625.   time    := number [tSep number [tSep number]] [mornStr | eveStr | timeSuff]
  69626.   tSep    := timeSep | sep
  69627.   date    := [dSep] dField [dSep dField [dSep dField [dSep dField [dSep]]]]
  69628.   dField  := number | dayOfWeek | abbrevMonth | month
  69629.   dSep    := dateSep | st0 | st1 | st2 | st3 | st4 | sep
  69630.   sep     := <non-alphanumeric>
  69631.  
  69632. The date defaults are the current day, month and year.  The time defaults to
  69633. 00:00:00.  The digits in a year are padded on the left, using the base date
  69634. (the date corresponding to zero seconds: Jan 1, 1904).  This routine uses the tokenizer
  69635. to separate the components of the strings.  It depends upon the names of the months
  69636. and weekdays used from international resources being single alphanumeric tokens.
  69637.  
  69638. Note that the date routine only fills in the year, month, day and dayOfWeek; the time
  69639. routine fills in only the hour, minute and second.  Thus the two routines can be
  69640. called sequentially to fill complementary values in the LongDateRec.
  69641.  
  69642. The return from the routine is a set of bits that indicate confidence levels, with
  69643. higher numbers indicating low confidence in how closely the input string matched what
  69644. the routine expected.  For example, inputting a time of 12.43.36 will work, but
  69645. return a message indicating that the separator was not standard.  This can also be
  69646. used to parse a string containing both the date and time, by using the confidence
  69647. levels to determine which portion comes first.  The returned bits include:
  69648.  
  69649. In C:
  69650.  
  69651.   #define fatalDateTime     0x8000
  69652.   #define longDateFound     1
  69653.   #define leftOverChars     2
  69654.   #define sepNotIntlSep     4
  69655.   #define fieldOrderNotIntl 8
  69656.   #define extraneousStrings 16
  69657.   #define tooManySeps       32
  69658.   #define sepNotConsistent  64
  69659.   #define tokenErr          0x8100
  69660.   #define cantReadUtilities 0x8200
  69661.   #define dateTimeNotFound  0x8400
  69662.   #define dateTimeInvalid   0x8800
  69663.  
  69664. æKY String2Time
  69665. æFc Script.h
  69666. æT Function
  69667. æD pascal String2DateStatus String2Time(Ptr textPtr,long textLen,DateCachePtr theCache,
  69668.     long *lengthUsed,LongDateRec *dateTime)
  69669.     = {0x2F3C,0x8214,0xFFF4,0xA8B5}; 
  69670. æDT String2DateStatus myVariable = String2Time((Ptr) textPtr,(long) textLen,(DateCachePtr) theCache,(
  69671.     long) * lengthUsed,(LongDateRec *) dateTime);
  69672. æC In Pascal:
  69673.  
  69674. Function String2Date(textPtr:  Ptr; textLen:   longint; theCache:  DateCachePtr;
  69675.     Var   lengthUsed:  Longint; Var   dateTime:  LongDateRec): String2DateStatus;
  69676.  
  69677. Function String2Time(textPtr:  Ptr; textLen:   longint; theCache:  DateCachePtr;
  69678.     Var   lengthUsed:  Longint; Var   dateTime:  LongDateRec): String2DateStatus;
  69679.  
  69680. In C:
  69681.  
  69682. pascal String2DateStatus String2Date(Ptr textPtr,long textLen,DateCachePtr theCache,
  69683.     long *lengthUsed,LongDateRec *dateTime); 
  69684.  
  69685. pascal String2DateStatus String2Time(Ptr textPtr,long textLen,DateCachePtr theCache,
  69686.     long *lengthUsed,LongDateRec *dateTime); 
  69687.  
  69688. These routines expect a date and time at the beginning of the text.  They parse the 
  69689. text, setting the lengthUsed to reflect the remainder of the text, and fill the 
  69690. dateTime record.
  69691.  
  69692. They recognize all the strings that are produced by the international date and time
  69693. utilities, and others.  For example, they will recognize the following dates: 
  69694. September 1, 1987; 1 Sept 1987; 1/9/1987; and 1 1987 Sept.
  69695.  
  69696. If the value of the input year is less than 100, then it is added to 1900; if less 
  69697. than 1000, then it is added to 1000 (the appropriate values are used from other 
  69698. calendars, gotten from the base date: LongDateTime = 0).  Thus the dates 1/9/1987 and 
  69699. 1/9/87 are equivalent.
  69700.  
  69701. The routines use the following grammar to interpret the date and time.  The relevant 
  69702. fields of the international utilities resources are used for separators, month and 
  69703. weekday names, and the ordering of the date elements.  The parsing is actually 
  69704. semantic-driven, so finer distinctions are made than those represented in the syntax 
  69705. diagram.
  69706.  
  69707.   time  := number [tSep number [tSep number]] [mornStr | eveStr | timeSuff]
  69708.   tSep  := timeSep | sep
  69709.   date  := [dSep] dField [dSep dField [dSep dField [dSep dField [dSep]]]]
  69710.   dField  := number | dayOfWeek | abbrevMonth | month
  69711.   dSep  := dateSep | st0 | st1 | st2 | st3 | st4 | sep
  69712.   sep  := <non-alphanumeric>
  69713.  
  69714. The date defaults are the current day, month and year.  The time defaults to 00:00:00.  
  69715. The digits in a year are padded on the left, using the base date (the date 
  69716. corresponding to zero seconds: Jan 1, 1904).  This routine uses the tokenizer to 
  69717. separate the components of the strings.  It depends upon the names of the months and 
  69718. weekdays used from international resources being single alphanumeric tokens.
  69719.  
  69720. Note that the date routine only fills in the year, month, day and dayOfWeek; the time 
  69721. routine fills in only the hour, minute and second.  Thus the two routines can be 
  69722. called sequentially to fill complementary values in the LongDateRec.
  69723.  
  69724. The return from the routine is a set of bits that indicate confidence levels, with 
  69725. higher numbers indicating low confidence in how closely the input string matched what 
  69726. the routine expected.  For example, inputting a time of 12.43.36 will work, but return 
  69727. a message indicating that the separator was not standard.  This can also be used to 
  69728. parse a string containing both the date and time, by using the confidence levels to 
  69729. determine which portion comes first.  The returned bits include:
  69730.  
  69731. In Pascal:
  69732.  
  69733. fatalDateTime       = $8000;
  69734. longDateFound       = 1;
  69735. leftOverChars       = 2;
  69736. sepNotIntlSep       = 4;
  69737. fieldOrderNotIntl   = 8;
  69738. extraneousStrings   = 16;
  69739. tooManySeps         = 32;
  69740. sepNotConsistent    = 64;
  69741. tokenErr            = $8100;
  69742. cantReadUtilities   = $8200;
  69743. dateTimeNotFound    = $8400;
  69744. dateTimeInvalid     = $8800;
  69745.  
  69746.  
  69747. In C:
  69748.  
  69749. #define fatalDateTime       0x8000
  69750. #define longDateFound       1
  69751. #define leftOverChars       2
  69752. #define sepNotIntlSep       4
  69753. #define fieldOrderNotIntl   8
  69754. #define extraneousStrings   16
  69755. #define tooManySeps         32
  69756. #define sepNotConsistent    64
  69757. #define tokenErr            0x8100
  69758. #define cantReadUtilities   0x8200
  69759. #define dateTimeNotFound    0x8400
  69760. #define dateTimeInvalid     0x8800
  69761.  
  69762. æKY LongDate2Secs
  69763. æFc Script.h
  69764. æT Function
  69765. æD pascal void LongDate2Secs(const LongDateRec *lDate,LongDateTime *lSecs)
  69766.     = {0x2F3C,0x8008,0xFFF2,0xA8B5}; 
  69767. æDT LongDate2Secs((const LongDateRec *) lDate,(LongDateTime *) lSecs);
  69768. æC 
  69769. In C:
  69770.  
  69771.   pascal void LongDate2Secs(const LongDateRec *lDate,LongDateTime *lSecs);
  69772.  
  69773.   pascal void LongSecs2Date(LongDateTime *lSecs,LongDateRec *lDate);
  69774.  
  69775. These routines extend the range of the Macintosh calendar as discussed above.  Any
  69776. fields that are not used should be zeroed.  On input, the LongDate2Secs routine will
  69777. use the day and month unless the day is zero; otherwise the dayOfYear is used unless
  69778. it is zero; otherwise the dayOfWeek and weekOfYear are used.
  69779.  
  69780. Other fields are additive: if you supply a month of 37, that will be interpreted as
  69781. adding 3 to the year, and using a month of 1.  This latter property is subject to
  69782. some restrictions imposed by the internal arithmetic: for example, | hour*60+minute |
  69783. must be less than 32767.
  69784.  
  69785. Two new interfaces have been added to Pack6 for LongDate support:
  69786.  
  69787. In C:
  69788.  
  69789.   pascal void IULDateString(LongDateTime *dateTime,DateForm longFlag,
  69790.                             Str255 result, Handle intlParam);
  69791.  
  69792.   pascal void IULTimeString(LongDateTime *dateTime,Boolean wantSeconds,
  69793.                            Str255 result, Handle intlParam);
  69794.  
  69795. These routines take a LongDateTime, and return a formatted string.  Only the old
  69796. fields year..second, and dayOfWeek are used.  If the intlParam is zero, then the
  69797. international resource 0 ('itl0') is used.  The output year is limited to four digits:
  69798. e.g., from 1 to 9999 A.D.
  69799.  
  69800. æKY LongSecs2Date
  69801. æFc Script.h
  69802. æT Function
  69803. æD pascal void LongSecs2Date(LongDateTime *lSecs,LongDateRec *lDate)
  69804.     = {0x2F3C,0x8008,0xFFF0,0xA8B5}; 
  69805. æDT LongSecs2Date((LongDateTime *) lSecs,(LongDateRec *) lDate);
  69806. æC 
  69807. In C:
  69808.  
  69809.   pascal void LongDate2Secs(const LongDateRec *lDate,LongDateTime *lSecs);
  69810.  
  69811.   pascal void LongSecs2Date(LongDateTime *lSecs,LongDateRec *lDate);
  69812.  
  69813. These routines extend the range of the Macintosh calendar as discussed above.  Any
  69814. fields that are not used should be zeroed.  On input, the LongDate2Secs routine will
  69815. use the day and month unless the day is zero; otherwise the dayOfYear is used unless
  69816. it is zero; otherwise the dayOfWeek and weekOfYear are used.
  69817.  
  69818. Other fields are additive: if you supply a month of 37, that will be interpreted as
  69819. adding 3 to the year, and using a month of 1.  This latter property is subject to
  69820. some restrictions imposed by the internal arithmetic: for example, | hour*60+minute |
  69821. must be less than 32767.
  69822.  
  69823. Two new interfaces have been added to Pack6 for LongDate support:
  69824.  
  69825. In C:
  69826.  
  69827.   pascal void IULDateString(LongDateTime *dateTime,DateForm longFlag,
  69828.                             Str255 result, Handle intlParam);
  69829.  
  69830.   pascal void IULTimeString(LongDateTime *dateTime,Boolean wantSeconds,
  69831.                            Str255 result, Handle intlParam);
  69832.  
  69833. These routines take a LongDateTime, and return a formatted string.  Only the old
  69834. fields year..second, and dayOfWeek are used.  If the intlParam is zero, then the
  69835. international resource 0 ('itl0') is used.  The output year is limited to four digits:
  69836. e.g., from 1 to 9999 A.D.
  69837.  
  69838. æKY ToggleDate
  69839. æFc Script.h
  69840. æT Function
  69841. æD pascal ToggleResults ToggleDate(LongDateTime *lSecs,LongDateField field,
  69842.     DateDelta delta,short ch,const TogglePB *params)
  69843.     = {0x2F3C,0x820E,0xFFEE,0xA8B5}; 
  69844. æDT ToggleResults myVariable = ToggleDate((LongDateTime *) lSecs,(LongDateField) field,()
  69845.     DateDelta delta,(short) ch,(const TogglePB *) params);
  69846. æC 
  69847. In C:
  69848.  
  69849.   pascal ToggleResults ToggleDate(LongDateTime *lSecs,LongDateField field,
  69850.                                   DateDelta delta,short ch,
  69851.                                   const TogglePB *params);
  69852.  
  69853.   pascal short ValidDate(LongDateRec *vDate,long flags,LongDateTime *newSecs);
  69854.  
  69855. The ToggleDate routine is used to modify a date or time record by toggling one of the
  69856. fields up or down.  The routine returns a valid date by performing two types of
  69857. action.  If the affected field overflows or underflows, then it will wrap to the
  69858. corresponding low or high value.  If changing the affected field causes other fields
  69859. to be invalid, then a close date is selected (which may cause other fields to change).
  69860.  For example, toggling the year upwards in February 29, 1980 results in March 1,
  69861. 1981.  Currently only the fields year..second, and am can be toggled, although this
  69862. should change in the future.
  69863.  
  69864. The routine will also toggle by character, if the delta = 0. The character will be
  69865. used to change the field in the following way.  If it is a digit, then it will be
  69866. added to the end of the field, and the field will be then modified to be valid in a
  69867. similar manner as in the alarm clock.  For example, if the minute is 54, then to
  69868. replace it by 23 by entering characters, first the minute will change to 42, then to
  69869. 23.  The AM/PM field will also use letters.
  69870.  
  69871. In C:
  69872.  
  69873.   struct TogglePB {
  69874.           long     togFlags;            
  69875.           ResType  amChars;                /*from intl0*/
  69876.           ResType  pmChars;                /*from intl0*/
  69877.           long     reserved[4];
  69878.   };
  69879.  
  69880. The parameter block should be set up as follows.  It should contain the uppercase
  69881. versions of the AM and PM strings to match (the defaults mornStr and eveStr can be
  69882. copied from the international utilities using IUGetIntl, and converted to uppercase
  69883. with UprText).
  69884.  
  69885. The ToggleDate routine makes an internal call to ValidDate, which can also be called
  69886. directly by the user.  ValidDate checks the date record for correctness, using the
  69887. params.togflags which is passed to it by ToggleDate.  If any of the record fields are
  69888. invalid, ValidDate returns a DateField value corresponding to the field in error. 
  69889. Otherwise, it returns a -1.
  69890.  
  69891. The params.togflags value passed to ValidDate by ToggleDate are the same for ToggleDate
  69892. and ValidDate.  The low word bits correspond to the values in the enumerated type
  69893. DateField.  For example, to check the validity of the year field you can create a
  69894. mask by doing the following:
  69895.  
  69896.   yearFieldMask = 2**yearField;
  69897.  
  69898. The high word of the flags value can be used to set various other conditions. The
  69899. only one currently used is a flag which can be set to restrict the range of valid
  69900. dates to the short date format (smallDateBit = 31; smallDateMask = $80000000).  All
  69901. other bits are reserved, and should be set to zero.  The reserved values should also
  69902. be zeroed.
  69903.  
  69904. Togflags should normally be set to $007F, which can be done by using the predeclared
  69905. constant dateStdMask.
  69906.  
  69907. •••Refer to Figure 11.•••
  69908.  
  69909. Figure 11–ToggleDate
  69910.  
  69911. æKY Str2Format
  69912. æFc Script.h
  69913. æT Function
  69914. æD pascal FormatStatus Str2Format(const Str255 inString,const NumberParts *partsTable,
  69915.     NumFormatString *outString)
  69916.     = {0x2F3C,0x820C,0xFFEC,0xA8B5}; 
  69917. æDT FormatStatus myVariable = Str2Format((const Str255) inString,(const NumberParts *) partsTable,(
  69918.     NumFormatString) * outString);
  69919. æC 
  69920. In C:
  69921.  
  69922.   pascal FormatStatus Str2Format(const Str255 inString,
  69923.                                  const NumberParts *partsTable,
  69924.                                  NumFormatString *outString);
  69925.  
  69926. Str2Format converts a string typed by the user into a canonical format.  It checks
  69927. the validity of the format string itself and also that of the NumberParts table,
  69928. because the NumberParts table is programmable by the application.
  69929.  
  69930. •••Refer to Figure 14.•••
  69931.  
  69932. Figure 14–Str2Format
  69933.  
  69934. æKY Format2Str
  69935. æFc Script.h
  69936. æT Function
  69937. æD pascal FormatStatus Format2Str(const NumFormatString *myCanonical,const NumberParts *partsTable,
  69938.     Str255 outString,TripleInt *positions)
  69939.     = {0x2F3C,0x8210,0xFFEA,0xA8B5}; 
  69940. æDT FormatStatus myVariable = Format2Str((const NumFormatString *) myCanonical,(const NumberParts *) partsTable,()
  69941.     Str255 outString,(TripleInt *) positions);
  69942. æC 
  69943. In C:
  69944.  
  69945.   pascal FormatStatus Format2Str(const NumFormatString *myCanonical,
  69946.   const NumberParts *partsTable,Str255 outString,TripleInt *positions);
  69947.  
  69948. Format2Str creates the string corresponding to a format definition string which has
  69949. been created by a prior call to Str2Format and according to the NumberParts table. 
  69950. It is the inverse operation of Str2Format.  This allows programs to display previously
  69951. entered formats for users to edit.
  69952.  
  69953. •••Refer to Figure 15.•••
  69954.  
  69955. Figure 15–Format2Str
  69956.  
  69957. æKY FormatX2Str
  69958. æFc Script.h
  69959. æT Function
  69960. æD pascal FormatStatus FormatX2Str(extended x,const NumFormatString *myCanonical,
  69961.     const NumberParts *partsTable,Str255 outString)
  69962.     = {0x2F3C,0x8210,0xFFE8,0xA8B5}; 
  69963. æDT FormatStatus myVariable = FormatX2Str((extended) x,(const NumFormatString *) myCanonical,(
  69964.     const NumberParts) * partsTable,(Str255) outString);
  69965. æC 
  69966. In C:
  69967.  
  69968.   pascal FormatStatus FormatX2Str(extended x,const NumFormatString *myCanonical,
  69969.                                   const NumberParts *partsTable,
  69970.                                   Str255 outString);
  69971.  
  69972. This routine creates a textual representation of a number according to a canonical
  69973. format which has been created by a prior call to Str2Format.
  69974.  
  69975. •••Refer to Figure 16.•••
  69976.  
  69977. Figure 16–FormatX2Str
  69978.  
  69979. æKY FormatStr2X
  69980. æFc Script.h
  69981. æT Function
  69982. æD 
  69983. pascal FormatStatus FormatStr2X(const Str255 source,const NumFormatString *myCanonical,
  69984.     const NumberParts *partsTable,extended *x)
  69985.     = {0x2F3C,0x8210,0xFFE6,0xA8B5}; 
  69986. æDT FormatStatus myVariable = FormatStr2X((const Str255) source,(const NumFormatString *) myCanonical,(
  69987.     const NumberParts) * partsTable,(extended *) x);
  69988. æC 
  69989. In C:
  69990.  
  69991.   pascal FormatStatus FormatStr2X(const Str255 source,
  69992.                                   const NumFormatString *myCanonical,
  69993.                                   const NumberParts *partsTable,extended *x);
  69994.  
  69995. This routine reads a textual representation of a number according to a canonical
  69996. format which has been created by a prior call to Str2Format, and creates an extended
  69997. floating point number which corresponds to that string.
  69998.  
  69999. Internally, the routine converts the string into a format acceptable to SANE, matching
  70000. against the three possible patterns in the canonical format.  If the input string
  70001. does not match any of the patterns, then FormatStr2X parses the string as best it can
  70002. returning the result.  Currently it is converted to a simple form, stripping non-digits
  70003. and replacing the decimal point, before calling SANE.
  70004.  
  70005. •••Refer to Figure 17.•••
  70006.  
  70007. Figure 17–FormatStr2X
  70008.  
  70009. æKY PortionText
  70010. æFc Script.h
  70011. æT Function
  70012. æD pascal Fixed PortionText(Ptr textPtr,long textLen)
  70013.     = {0x2F3C,0x8408,0x0024,0xA8B5}; 
  70014. æDT Fixed myVariable = PortionText((Ptr) textPtr,(long) textLen);
  70015. æC 
  70016. In C:
  70017.  
  70018.   pascal Fixed PortionText(Ptr textPtr,long textLen);
  70019.  
  70020. This routine returns a result which indicates the proportion of justification that
  70021. should be allocated to this text when compared to other text.  It is used when justifying
  70022. a sequence of format runs, so that the appropriate amount of extra width is apportioned
  70023. properly among them.  For example, suppose that there are three format runs on a
  70024. line: A, B, and C.  The line needs to be widened by 11 pixels for justification. 
  70025. Calling PortionText on these format runs yields the first row in the following table:
  70026.  
  70027.                   A       B              C       Total
  70028.  
  70029.   PortionText:    5.4     7.3            8.2      20.9
  70030.   Normalized:      .258    .349    remainder       1.00
  70031.   Pixels (p):     2.84    3.84     remainder      11.0
  70032.   Rounded (r):    3       4        remainder      11
  70033.  
  70034. The proportion of the justification to be allotted to A is 25.8%, so it receives 3
  70035. pixels out of 11.  In general, to prevent rounding errors,
  70036. rn = round(∑1..nP) – ∑1..n–1 r (which can be computed iteratively);
  70037. e.g., rB is round(3.84+2.84) – 3, and rC is round(11.0) – 7.
  70038.  
  70039. For normal Roman text, the result is currently a function of the number of spaces in
  70040. the text, the number of other characters in the text, and the font size (the raw
  70041. size, not ascent + descent + leading).  This may change in the future, so values
  70042. should be compared at the time of execution.
  70043.  
  70044. •••Refer to Figure 5.•••
  70045.  
  70046. Figure 5–PortionText
  70047.  
  70048. æKY FindScriptRun
  70049. æFc Script.h
  70050. æT Function
  70051. æD pascal struct ScriptRunStatus FindScriptRun(Ptr textPtr,long textLen,long *lenUsed)
  70052.     = {0x2F3C,0x820C,0x0026,0xA8B5}; 
  70053. æDT struct ScriptRunStatus myVariable = FindScriptRun((Ptr) textPtr,(long) textLen,(long *) lenUsed);
  70054. æC 
  70055. In C:
  70056.  
  70057.   pascal struct ScriptRunStatus FindScriptRun(Ptr textPtr,long textLen,
  70058.                                               long *lenUsed);
  70059.  
  70060.   struct ScriptRunStatus {
  70061.             short  script;
  70062.             short  variant;
  70063.   };
  70064.  
  70065.   char             *mychararray = 'abcDEFghi';
  70066.   char             *textptr;
  70067.   long             textlength;
  70068.   ScriptRunStatus  srs;
  70069.   long             lenused;
  70070.  
  70071.   srs = FindScriptRun(mychararray,(long)strlen(mychararray),&lenUsed);
  70072.   /* lenUsed would now = 3, blocktype would equal 0 */
  70073.   /* we can point at the remainder of the text with the following code */
  70074.   textptr = mychararray + lenUsed;
  70075.   textlen = strlen(mychararray) - lenUsed;
  70076.  
  70077. For compatibility, each script allows Roman text to be mixed in.  This routine is
  70078. used to break up mixed text (Roman & Native) into blocks.  The lenUsed is set to
  70079. reflect the length of the remaining text.  The return value reflects the type of
  70080. block: the upper byte is the script (0 being Roman text) and the lower byte being
  70081. script-specific (script systems can return types of native sub-scripts, such as
  70082. Kanji, Katakana and Hiragana for Japanese).  For example, given that the capital
  70083. letters represent Hebrew text:
  70084.  
  70085. In Pascal:
  70086.  
  70087.   myCharArray = 'abcDEFghi';
  70088.   myCharPtr := @myCharArray;
  70089.   blockType := FindScriptRun (myCharPtr, 9, lenUsed);
  70090.   {lenUsed = 3, blockType = 0: get remainder of text with: }
  70091.   textPtr := Ptr(ord(textPtr)+lenUsed);
  70092.   textLen := textLen-lenUsed;
  70093.  
  70094. æKY VisibleLength
  70095. æFc Script.h
  70096. æT Function
  70097. æD pascal long VisibleLength(Ptr textPtr,long textLen)
  70098.     = {0x2F3C,0x8408,0x0028,0xA8B5}; 
  70099. æDT long myVariable = VisibleLength((Ptr) textPtr,(long) textLen);
  70100. æC 
  70101. In C:
  70102.  
  70103.   pascal long VisibleLength(Ptr textPtr,long textLen);
  70104.  
  70105. This routine returns the length of the text excluding trailing white space, taking
  70106. into account the script of the text.  Trailing white space is only excluded if it
  70107. occurs on the visible right side, in display order.
  70108.  
  70109. •••Refer to Figure 8.•••
  70110.  
  70111. Figure 8–VisibleLength
  70112.  
  70113. For example, in Pascal:
  70114.  
  70115.   myVisibleLength := VisibleLength(myText,myOffset);
  70116.   curSlop := myPixel - TextWidth(myText,0,myVisibleLength);
  70117.   DrawJust(myText,myVisibleLength,curSlop);
  70118.  
  70119. æKY ValidDate
  70120. æFc Script.h
  70121. æT Function
  70122. æD pascal short ValidDate(LongDateRec *vDate,long flags,LongDateTime *newSecs)
  70123.     = {0x2F3C,0x8204,0xFFE4,0xA8B5}; 
  70124. æDT short myVariable = ValidDate((LongDateRec *) vDate,(long) flags,(LongDateTime *) newSecs);
  70125. æC 
  70126. In C:
  70127.  
  70128.   pascal ToggleResults ToggleDate(LongDateTime *lSecs,LongDateField field,
  70129.                                   DateDelta delta,short ch,
  70130.                                   const TogglePB *params);
  70131.  
  70132.   pascal short ValidDate(LongDateRec *vDate,long flags,LongDateTime *newSecs);
  70133.  
  70134. The ToggleDate routine is used to modify a date or time record by toggling one of the
  70135. fields up or down.  The routine returns a valid date by performing two types of
  70136. action.  If the affected field overflows or underflows, then it will wrap to the
  70137. corresponding low or high value.  If changing the affected field causes other fields
  70138. to be invalid, then a close date is selected (which may cause other fields to change).
  70139.  For example, toggling the year upwards in February 29, 1980 results in March 1,
  70140. 1981.  Currently only the fields year..second, and am can be toggled, although this
  70141. should change in the future.
  70142.  
  70143. The routine will also toggle by character, if the delta = 0. The character will be
  70144. used to change the field in the following way.  If it is a digit, then it will be
  70145. added to the end of the field, and the field will be then modified to be valid in a
  70146. similar manner as in the alarm clock.  For example, if the minute is 54, then to
  70147. replace it by 23 by entering characters, first the minute will change to 42, then to
  70148. 23.  The AM/PM field will also use letters.
  70149.  
  70150. In C:
  70151.  
  70152.   struct TogglePB {
  70153.           long     togFlags;            
  70154.           ResType  amChars;                /*from intl0*/
  70155.           ResType  pmChars;                /*from intl0*/
  70156.           long     reserved[4];
  70157.   };
  70158.  
  70159. The parameter block should be set up as follows.  It should contain the uppercase
  70160. versions of the AM and PM strings to match (the defaults mornStr and eveStr can be
  70161. copied from the international utilities using IUGetIntl, and converted to uppercase
  70162. with UprText).
  70163.  
  70164. The ToggleDate routine makes an internal call to ValidDate, which can also be called
  70165. directly by the user.  ValidDate checks the date record for correctness, using the
  70166. params.togflags which is passed to it by ToggleDate.  If any of the record fields are
  70167. invalid, ValidDate returns a DateField value corresponding to the field in error. 
  70168. Otherwise, it returns a -1.
  70169.  
  70170. The params.togflags value passed to ValidDate by ToggleDate are the same for ToggleDate
  70171. and ValidDate.  The low word bits correspond to the values in the enumerated type
  70172. DateField.  For example, to check the validity of the year field you can create a
  70173. mask by doing the following:
  70174.  
  70175.   yearFieldMask = 2**yearField;
  70176.  
  70177. The high word of the flags value can be used to set various other conditions. The
  70178. only one currently used is a flag which can be set to restrict the range of valid
  70179. dates to the short date format (smallDateBit = 31; smallDateMask = $80000000).  All
  70180. other bits are reserved, and should be set to zero.  The reserved values should also
  70181. be zeroed.
  70182.  
  70183. Togflags should normally be set to $007F, which can be done by using the predeclared
  70184. constant dateStdMask.
  70185.  
  70186. •••Refer to Figure 11.•••
  70187.  
  70188. Figure 11–ToggleDate
  70189.  
  70190. æKY NFindWord
  70191. æFc Script.h
  70192. æT Function
  70193. æD pascal void NFindWord(Ptr textPtr,short textLength,short offset,Boolean leadingEdge,
  70194.     NBreakTablePtr nbreaks,OffsetTable offsets)
  70195.     = {0x2F3C,0x8012,0xFFE2,0xA8B5}; 
  70196. æDT NFindWord((Ptr) textPtr,(short) textLength,(short) offset,(Boolean) leadingEdge,()
  70197.     NBreakTablePtr nbreaks,(OffsetTable) offsets);
  70198. æC 
  70199.  
  70200. æKY TruncString
  70201. æFc Script.h
  70202. æT Function
  70203. æD pascal short TruncString(short width,const Str255 theString,TruncCode truncWhere)
  70204.     = {0x2F3C,0x8208,0xFFE0,0xA8B5}; 
  70205. æDT short myVariable = TruncString((short) width,(const Str255) theString,(TruncCode) truncWhere);
  70206. æC 
  70207.  
  70208. æKY TruncText
  70209. æFc Script.h
  70210. æT Function
  70211. æD pascal short TruncText(short width,Ptr textPtr,short *length,TruncCode truncWhere)
  70212.     = {0x2F3C,0x820C,0xFFDE,0xA8B5}; 
  70213. æDT short myVariable = TruncText((short) width,(Ptr) textPtr,(short *) length,(TruncCode) truncWhere);
  70214. æC 
  70215.  
  70216. æKY ReplaceText
  70217. æFc Script.h
  70218. æT Function
  70219. æD pascal short ReplaceText(Handle baseText,Handle substitutionText,const Str15 key)
  70220.     = {0x2F3C,0x820C,0xFFDC,0xA8B5}; 
  70221. æDT short myVariable = ReplaceText((Handle) baseText,(Handle) substitutionText,(const Str15) key);
  70222. æC 
  70223.  
  70224. æKY NPixel2Char
  70225. æFc Script.h
  70226. æT Function
  70227. æTN A8B5
  70228. æD pascal short NPixel2Char(Ptr textBuf,long textLen,Fixed slop,Fixed pixelWidth,
  70229.     Boolean *leadingEdge,Fixed *widthRemaining,JustStyleCode styleRunPosition)
  70230.     = {0x2F3C,0x821A,0x002E,0xA8B5}; 
  70231. æDT short myVariable = NPixel2Char((Ptr) textBuf,(long) textLen,(Fixed) slop,(Fixed) pixelWidth,(
  70232.     Boolean) * leadingEdge,(Fixed *) widthRemaining,(JustStyleCode) styleRunPosition);
  70233. æC 
  70234.  
  70235. æKY NChar2Pixel
  70236. æFc Script.h
  70237. æT Function
  70238. æTN A8B5
  70239. æD pascal short NChar2Pixel(Ptr textBuf,long textLen,Fixed slop,long offset,
  70240.     sort direction,JustStyleCode styleRunPosition)
  70241.     = {0x2F3C,0x8214,0x0030,0xA8B5}; 
  70242. æDT short myVariable = NChar2Pixel((Ptr) textBuf,(long) textLen,(Fixed) slop,(long) offset,()
  70243.     sort direction,(JustStyleCode) styleRunPosition);
  70244. æC 
  70245.  
  70246. æKY NDrawJust
  70247. æFc Script.h
  70248. æT Function
  70249. æTN A8B5
  70250. æD pascal void NDrawJust(Ptr textBuf,long textLen,Fixed slop,JustStyleCode styleRunPosition)
  70251.     = {0x2F3C,0x800E,0x0032,0xA8B5}; 
  70252. æDT NDrawJust((Ptr) textBuf,(long) textLen,(Fixed) slop,(JustStyleCode) styleRunPosition);
  70253. æC 
  70254.  
  70255. æKY NMeasureJust
  70256. æFc Script.h
  70257. æT Function
  70258. æTN A8B5
  70259. æD pascal void NMeasureJust(Ptr textBuf,long textLen,Fixed slop,Ptr charLocs,
  70260.     JustStyleCode styleRunPosition)
  70261.     = {0x2F3C,0x8012,0x0034,0xA8B5}; 
  70262. æDT NMeasureJust((Ptr) textBuf,(long) textLen,(Fixed) slop,(Ptr) charLocs,()
  70263.     JustStyleCode styleRunPosition);
  70264. æC 
  70265.  
  70266. æKY NPortionText
  70267. æFc Script.h
  70268. æT Function
  70269. æTN A8B5
  70270. æD pascal Fixed NPortionText(Ptr textBuf,long textLen,JustStyleCode styleRunPosition,
  70271.     Ptr charLocs,JustStyleCode styleRunPosition)
  70272.     = {0x2F3C,0x840A,0x0036,0xA8B5}; 
  70273. æDT Fixed myVariable = NPortionText((Ptr) textBuf,(long) textLen,(JustStyleCode) styleRunPosition,()
  70274.     Ptr charLocs,(JustStyleCode) styleRunPosition);
  70275. æC 
  70276.  
  70277.  
  70278. æKY SCSI.h
  70279. æKL SCSICmd
  70280. SCSIComplete
  70281. SCSIGet
  70282. SCSIMsgIn
  70283. SCSIMsgOut
  70284. SCSIRBlind
  70285. SCSIRead
  70286. SCSIReset
  70287. SCSISelAtn
  70288. SCSISelect
  70289. SCSIStat
  70290. SCSIWBlind
  70291. SCSIWrite
  70292.  
  70293. Block0
  70294. Partition
  70295. pMapSIG
  70296. sbSIGWord
  70297. scAdd
  70298. scArbNBErr
  70299. scBadParmsErr
  70300. scBusTOErr
  70301. scCommErr
  70302. scComp
  70303. scCompareErr
  70304. scComplPhaseErr
  70305. scInc
  70306. scLoop
  70307. scMgrBusyErr
  70308. scMove
  70309. scNoInc
  70310. scNop
  70311. scPhaseErr
  70312. scSequenceErr
  70313. SCSIInstr
  70314. scStop
  70315.  
  70316. æKY scInc
  70317. æFc SCSI.h
  70318. æT #define
  70319. æD #define scInc 1
  70320. æC 
  70321.  
  70322. æKY scNoInc
  70323. æFc SCSI.h
  70324. æT #define
  70325. æD #define scNoInc 2
  70326. æC 
  70327.  
  70328. æKY scAdd
  70329. æFc SCSI.h
  70330. æT #define
  70331. æD #define scAdd 3
  70332. æC 
  70333.  
  70334. æKY scMove
  70335. æFc SCSI.h
  70336. æT #define
  70337. æD #define scMove 4
  70338. æC 
  70339.  
  70340. æKY scLoop
  70341. æFc SCSI.h
  70342. æT #define
  70343. æD #define scLoop 5
  70344. æC 
  70345.  
  70346. æKY scNop
  70347. æFc SCSI.h
  70348. æT #define
  70349. æD #define scNop 6
  70350. æC 
  70351.  
  70352. æKY scStop
  70353. æFc SCSI.h
  70354. æT #define
  70355. æD #define scStop 7
  70356. æC 
  70357.  
  70358. æKY scComp
  70359. æFc SCSI.h
  70360. æT #define
  70361. æD #define scComp 8
  70362. æC 
  70363.  
  70364. æKY scCommErr
  70365. æFc SCSI.h
  70366. æT #define
  70367. æD #define scCommErr 2 /*communications error, operation timeout*/
  70368. æC 
  70369.   /* SCSI Manager result codes */
  70370.  
  70371.   scCommErr         2    Breakdown in SCSI protocols:  usually no device
  70372.                          connected or bus not terminated
  70373.   scArbNBErr        3    Arbitration failed during SCSIGet; bus busy
  70374.   scBadParmsErr     4    Unrecognized instruction in transfer
  70375.                          instruction block
  70376.   scPhaseErr        5    Phase error:  target and initiator not in
  70377.                          agreement as to type of information to transfer
  70378.   scCompareErr      6    Data comparison error during read (with SCCOMP
  70379.                          instruction in transfer instruction block)
  70380.   scMgrBusyErr      7    SCSI Manager busy with another operation
  70381.                          when SCSIGet was called
  70382.   scSequenceErr     8    Attempted operation is out of sequence;
  70383.                          e.g., calling SCSISelect before doing SCSIGet
  70384.   scBusTOErr        9    Bus timeout before data ready on SCSIRBlind
  70385.                          and SCSIWBlind
  70386.   scComplPhaseErr  10    SCSIComplete failed; bus not in Status phase
  70387.  
  70388. æKY scArbNBErr
  70389. æFc SCSI.h
  70390. æT #define
  70391. æD #define scArbNBErr 3 /*arbitration timeout waiting for not BSY*/
  70392. æC 
  70393.  
  70394. æKY scBadParmsErr
  70395. æFc SCSI.h
  70396. æT #define
  70397. æD #define scBadParmsErr 4 /*bad parameter or TIB opcode*/
  70398. æC 
  70399.  
  70400. æKY scPhaseErr
  70401. æFc SCSI.h
  70402. æT #define
  70403. æD #define scPhaseErr 5 /*SCSI bus not in correct phase for attempted operation*/
  70404. æC 
  70405.  
  70406. æKY scCompareErr
  70407. æFc SCSI.h
  70408. æT #define
  70409. æD #define scCompareErr 6 /*data compare error*/
  70410. æC 
  70411.  
  70412. æKY scMgrBusyErr
  70413. æFc SCSI.h
  70414. æT #define
  70415. æD #define scMgrBusyErr 7 /*SCSI Manager busy */
  70416. æC 
  70417.  
  70418. æKY scSequenceErr
  70419. æFc SCSI.h
  70420. æT #define
  70421. æD #define scSequenceErr 8 /*attempted operation is out of sequence*/
  70422. æC 
  70423.  
  70424. æKY scBusTOErr
  70425. æFc SCSI.h
  70426. æT #define
  70427. æD #define scBusTOErr 9 /*CPU bus timeout*/
  70428. æC 
  70429.  
  70430. æKY scComplPhaseErr
  70431. æFc SCSI.h
  70432. æT #define
  70433. æD #define scComplPhaseErr 10 /*SCSI bus wasn't in Status phase*/
  70434. æC 
  70435.  
  70436. æKY sbSIGWord
  70437. æFc SCSI.h
  70438. æT #define
  70439. æD #define sbSIGWord 0x4552
  70440. æC 
  70441.  
  70442. æKY pMapSIG
  70443. æFc SCSI.h
  70444. æT #define
  70445. æD #define pMapSIG 0x504D
  70446. æC 
  70447.  
  70448. æKY Block0
  70449. æFc SCSI.h
  70450. æT struct
  70451. æD struct Block0 {
  70452.     unsigned short sbSig; /*unique value for SCSI block 0*/
  70453.     unsigned short sbBlkSize; /*block size of device*/
  70454.     unsigned long sbBlkCount; /*number of blocks on device*/
  70455.     unsigned short sbDevType; /*device type*/
  70456.     unsigned short sbDevId; /*device id*/
  70457.     unsigned long sbData; /*not used*/
  70458.     unsigned short sbDrvrCount; /*driver descriptor count*/
  70459.     unsigned long ddBlock; /*1st driver's starting block*/
  70460.     unsigned short ddSize; /*size of 1st driver (512-byte blks)*/
  70461.     unsigned short ddType; /*system type (1 for Mac+)*/
  70462.     unsigned short ddPad[243]; /*ARRAY[0..242] OF INTEGER; not used*/
  70463. };
  70464.  
  70465. typedef struct Block0 Block0;
  70466. æC 
  70467.  
  70468. æKY Partition
  70469. æFc SCSI.h
  70470. æT struct
  70471. æD struct Partition {
  70472.     unsigned short pmSig; /*unique value for map entry blk*/
  70473.     unsigned short pmSigPad; /*currently unused*/
  70474.     unsigned long pmMapBlkCnt; /*# of blks in partition map*/
  70475.     unsigned long pmPyPartStart; /*physical start blk of partition*/
  70476.     unsigned long pmPartBlkCnt; /*# of blks in this partition*/
  70477.     unsigned char pmPartName[32]; /*ASCII partition name*/
  70478.     unsigned char pmParType[32]; /*ASCII partition type*/
  70479.     unsigned long pmLgDataStart; /*log. # of partition's 1st data blk*/
  70480.     unsigned long pmDataCnt; /*# of blks in partition's data area*/
  70481.     unsigned long pmPartStatus; /*bit field for partition status*/
  70482.     unsigned long pmLgBootStart; /*log. blk of partition's boot code*/
  70483.     unsigned long pmBootSize; /*number of bytes in boot code*/
  70484.     unsigned long pmBootAddr; /*memory load address of boot code*/
  70485.     unsigned long pmBootAddr2; /*currently unused*/
  70486.     unsigned long pmBootEntry; /*entry point of boot code*/
  70487.     unsigned long pmBootEntry2; /*currently unused*/
  70488.     unsigned long pmBootCksum; /*checksum of boot code*/
  70489.     unsigned char pmProcessor[16]; /*ASCII for the processor type*/
  70490.     unsigned short pmPad[188]; /*512 bytes long currently unused*/
  70491. };
  70492.  
  70493. typedef struct Partition Partition;
  70494. æC 
  70495.  
  70496. æKY SCSIInstr
  70497. æFc SCSI.h
  70498. æT struct
  70499. æD struct SCSIInstr {
  70500.     unsigned short scOpcode;
  70501.     unsigned long scParam1;
  70502.     unsigned long scParam2;
  70503. };
  70504.  
  70505. typedef struct SCSIInstr SCSIInstr;
  70506. æC 
  70507. »Describing the Operation to be Performed
  70508.  
  70509. You tell the SCSI Manager what operation to perform by passing a pointer to a command
  70510. descriptor block; the SCSI command structure is outlined in the ANSC document X3T9.2/82-2.
  70511.  
  70512. When the command to be performed involves a transfer of data (such as a read or write
  70513. operation), you also need to pass a pointer to a transfer instruction block, which
  70514. tells the SCSI Manager what to do with the data bytes transferred during the data
  70515. phase. A transfer instruction block contains a pseudo-program consisting of a variable
  70516. number of instructions; it’s similar to a subroutine except that the instructions are
  70517. provided and interpreted by the SCSI Manager itself. The instructions are of a fixed
  70518. size and have the following structure:
  70519.  
  70520. TYPE  SCSIInstr = RECORD
  70521.                     scOpcode:  INTEGER;    {operation code}
  70522.                     scParam1:  LONGINT;    {first parameter}
  70523.                     scParam2:  LONGINT     {second parameter}
  70524.                   END;
  70525.  
  70526. Eight instructions are available; their operation codes are specified with the following
  70527. predefined constants:
  70528.  
  70529. CONST  scInc    = 1;    {SCINC instruction}
  70530.        scNoInc  = 2;    {SCNOINC instruction}
  70531.        scAdd    = 3;    {SCADD instruction}
  70532.        scMove   = 4;    {SCMOVE instruction}
  70533.        scLoop   = 5;    {SCLOOP instruction}
  70534.        scNOp    = 6;    {SCNOP instruction}
  70535.        scStop   = 7;    {SCSTOP instruction}
  70536.        scComp   = 8;    {SCCOMP instruction}
  70537.  
  70538. A description of the instructions is given below.
  70539.  
  70540. opcode = scInc    param1 = buffer    param2 = count
  70541.  
  70542. The SCINC instruction moves count data bytes to or from buffer, incrementing buffer
  70543. by count when done.
  70544.  
  70545. opcode = scNoInc    param1 = buffer    param2 = count
  70546.  
  70547. The SCNOINC instruction moves count data bytes to or from buffer, leaving buffer
  70548. unmodified.
  70549.  
  70550. opcode = scAdd    param1 = addr    param2 = value
  70551.  
  70552. The SCADD instruction adds the given value to the address in addr. (The addition is
  70553. performed as an MC68000 long operation.)
  70554.  
  70555. opcode = scMove    param1 = addr1    param2 = addr2
  70556.  
  70557. The SCMOVE instruction moves the value pointed at by addr1 to the location pointed to
  70558. by addr2. (The move is an MC68000 long operation.)
  70559.  
  70560. opcode = scLoop    param1 = relAddr    param2 = count
  70561.  
  70562. The SCLOOP instruction decrements count by 1. If the result is greater than 0, pseudo-program
  70563. execution resumes at the current address+relAddr. If the result is 0, pseudo-program
  70564. execution resumes at the next instruction. RelAddr should be a signed multiple of the
  70565. instruction size (10 bytes). For example, to loop to the immediately preceding instruction,
  70566. the relAddr field would contain –10. To loop forward by three instructions, it would
  70567. contain 30.
  70568.  
  70569. opcode = scNOp    param1 = NIL    param2 = NIL
  70570.  
  70571. The SCNOP instruction does nothing.
  70572.  
  70573. opcode = scStop    param1 = NIL    param2 = NIL
  70574.  
  70575. The SCSTOP instruction terminates the pseudo-program execution, returning to the
  70576. calling SCSI Manager routine.
  70577.  
  70578. opcode = scComp    param1 = addr    param2 = count
  70579.  
  70580. The SCCOMP instruction is used only with a read command. Beginning at addr, it compares
  70581. incoming data bytes with memory, incrementing addr by count when done. If the bytes
  70582. do not compare equally, an error is returned to the read command.
  70583.  
  70584. »Example
  70585.  
  70586. This example gives a transfer instruction block for a transfer of six 512-byte blocks
  70587. of data from or to address $67B50.
  70588.  
  70589.   SCINC     $67B50    512
  70590.   SCLOOP    -10       6
  70591.   SCSTOP
  70592.  
  70593. æKY SCSIReset
  70594. æFc SCSI.h
  70595. æT Function
  70596. æD pascal OSErr SCSIReset(void); 
  70597. æDT OSErr myVariable = SCSIReset()(void);
  70598. æRI IV-289
  70599. æC 
  70600. »Assembly-language note:  Unlike most other Operating System routines, the SCSI
  70601.                          Manager routines are stack-based.  You can invoke each
  70602.                          of the SCSI routines with a macro that has the same
  70603.                          name as the routine preceded by an underscore.  These
  70604.                          macros, however, aren’t trap macros themselves;
  70605.                          instead they expand to invoke the trap macro
  70606.                          _SCSIDispatch.  The SCSI Manager determines which
  70607.                          routine to execute from the routine selector, an
  70608.                          integer that’s passed to it in a word on the stack.
  70609.                          The routine selectors for the new routines are as
  70610.                          follows:
  70611.  
  70612.                            scsiReset     .EQU    0
  70613.                            scsiGet       .EQU    1
  70614.                            scsiSelect    .EQU    2
  70615.                            scsiCmd       .EQU    3
  70616.                            scsiComplete  .EQU    4
  70617.                            scsiRead      .EQU    5
  70618.                            scsiWrite     .EQU    6
  70619.                            scsiRBlind    .EQU    8
  70620.                            scsiWBlind    .EQU    9
  70621.                            scsiStat      .EQU    10
  70622.                            scsiSelAtn    .EQU    11
  70623.                            scsiMsgIn     .EQU    12
  70624.                            scsiMsgOut    .EQU    13
  70625.  
  70626. If you specify a routine selector that’s not defined, the System Error Handler is
  70627. called with the system error ID dsCoreErr.
  70628.  
  70629. Most of the SCSI Manager routines return an integer result code of type OSErr. Each
  70630. routine lists all of the applicable result codes, along with a short description of
  70631. what the result code means. Lengthier explanations of all the result codes can be
  70632. found in the summary at the end of this chapter.  The error scSequenceErr is not
  70633. listed under each operation.  It is returned when an attempted operation is out of
  70634. sequence (calling SCSISelect without first calling SCSIGet, for instance).
  70635.  
  70636. Warning:  The error codes returned by SCSI Manager routines typically indicate
  70637.           only that a given operation failed. To determine the actual cause of
  70638.           the failure, you need to send another SCSI command asking the device
  70639.           what went wrong.
  70640.  
  70641. SCSIReset resets the SCSI bus.
  70642.  
  70643. Result codes    noErr      No error
  70644.                 commErr    Breakdown in SCSI protocols
  70645.  
  70646. æKY SCSIGet
  70647. æFc SCSI.h
  70648. æT Function
  70649. æD pascal OSErr SCSIGet(void); 
  70650. æDT OSErr myVariable = SCSIGet()(void);
  70651. æRT 96
  70652. æRI IV-289, N96-3
  70653. æC 
  70654. »Assembly-language note:  Unlike most other Operating System routines, the SCSI
  70655.                          Manager routines are stack-based.  You can invoke each
  70656.                          of the SCSI routines with a macro that has the same
  70657.                          name as the routine preceded by an underscore.  These
  70658.                          macros, however, aren’t trap macros themselves;
  70659.                          instead they expand to invoke the trap macro
  70660.                          _SCSIDispatch.  The SCSI Manager determines which
  70661.                          routine to execute from the routine selector, an
  70662.                          integer that’s passed to it in a word on the stack.
  70663.                          The routine selectors for the new routines are as
  70664.                          follows:
  70665.  
  70666.                            scsiReset     .EQU    0
  70667.                            scsiGet       .EQU    1
  70668.                            scsiSelect    .EQU    2
  70669.                            scsiCmd       .EQU    3
  70670.                            scsiComplete  .EQU    4
  70671.                            scsiRead      .EQU    5
  70672.                            scsiWrite     .EQU    6
  70673.                            scsiRBlind    .EQU    8
  70674.                            scsiWBlind    .EQU    9
  70675.                            scsiStat      .EQU    10
  70676.                            scsiSelAtn    .EQU    11
  70677.                            scsiMsgIn     .EQU    12
  70678.                            scsiMsgOut    .EQU    13
  70679.  
  70680. If you specify a routine selector that’s not defined, the System Error Handler is
  70681. called with the system error ID dsCoreErr.
  70682.  
  70683. Most of the SCSI Manager routines return an integer result code of type OSErr. Each
  70684. routine lists all of the applicable result codes, along with a short description of
  70685. what the result code means. Lengthier explanations of all the result codes can be
  70686. found in the summary at the end of this chapter.  The error scSequenceErr is not
  70687. listed under each operation.  It is returned when an attempted operation is out of
  70688. sequence (calling SCSISelect without first calling SCSIGet, for instance).
  70689.  
  70690. Warning:  The error codes returned by SCSI Manager routines typically indicate
  70691.           only that a given operation failed. To determine the actual cause of
  70692.           the failure, you need to send another SCSI command asking the device
  70693.           what went wrong.
  70694.  
  70695. SCSIGet arbitrates for use of the SCSI bus.
  70696.  
  70697. Result codes    noErr           No error
  70698.                 commErr         Breakdown in SCSI protocols
  70699.                 scArbNBErr      Bus is busy
  70700.                 scMgrBusyErr    SCSI Manager busy with another operation
  70701.  
  70702. æKY SCSISelect
  70703. æFc SCSI.h
  70704. æT Function
  70705. æD pascal OSErr SCSISelect(short targetID); 
  70706. æDT OSErr myVariable = SCSISelect((short) targetID);
  70707. æRI IV-290
  70708. æC 
  70709. »Assembly-language note:  Unlike most other Operating System routines, the SCSI
  70710.                          Manager routines are stack-based.  You can invoke each
  70711.                          of the SCSI routines with a macro that has the same
  70712.                          name as the routine preceded by an underscore.  These
  70713.                          macros, however, aren’t trap macros themselves;
  70714.                          instead they expand to invoke the trap macro
  70715.                          _SCSIDispatch.  The SCSI Manager determines which
  70716.                          routine to execute from the routine selector, an
  70717.                          integer that’s passed to it in a word on the stack.
  70718.                          The routine selectors for the new routines are as
  70719.                          follows:
  70720.  
  70721.                            scsiReset     .EQU    0
  70722.                            scsiGet       .EQU    1
  70723.                            scsiSelect    .EQU    2
  70724.                            scsiCmd       .EQU    3
  70725.                            scsiComplete  .EQU    4
  70726.                            scsiRead      .EQU    5
  70727.                            scsiWrite     .EQU    6
  70728.                            scsiRBlind    .EQU    8
  70729.                            scsiWBlind    .EQU    9
  70730.                            scsiStat      .EQU    10
  70731.                            scsiSelAtn    .EQU    11
  70732.                            scsiMsgIn     .EQU    12
  70733.                            scsiMsgOut    .EQU    13
  70734.  
  70735. If you specify a routine selector that’s not defined, the System Error Handler is
  70736. called with the system error ID dsCoreErr.
  70737.  
  70738. Most of the SCSI Manager routines return an integer result code of type OSErr. Each
  70739. routine lists all of the applicable result codes, along with a short description of
  70740. what the result code means. Lengthier explanations of all the result codes can be
  70741. found in the summary at the end of this chapter.  The error scSequenceErr is not
  70742. listed under each operation.  It is returned when an attempted operation is out of
  70743. sequence (calling SCSISelect without first calling SCSIGet, for instance).
  70744.  
  70745. Warning:  The error codes returned by SCSI Manager routines typically indicate
  70746.           only that a given operation failed. To determine the actual cause of
  70747.           the failure, you need to send another SCSI command asking the device
  70748.           what went wrong.
  70749.  
  70750. SCSISelect selects the device whose ID is in targetID.
  70751.  
  70752. Result codes    noErr      No error
  70753.                 commErr    Breakdown in SCSI protocols
  70754.  
  70755. æKY SCSICmd
  70756. æFc SCSI.h
  70757. æT Function
  70758. æD pascal OSErr SCSICmd(Ptr buffer,short count); 
  70759. æDT OSErr myVariable = SCSICmd((Ptr) buffer,(short) count);
  70760. æRT 96
  70761. æRI IV-290, N96-3
  70762. æC 
  70763. »Assembly-language note:  Unlike most other Operating System routines, the SCSI
  70764.                          Manager routines are stack-based.  You can invoke each
  70765.                          of the SCSI routines with a macro that has the same
  70766.                          name as the routine preceded by an underscore.  These
  70767.                          macros, however, aren’t trap macros themselves;
  70768.                          instead they expand to invoke the trap macro
  70769.                          _SCSIDispatch.  The SCSI Manager determines which
  70770.                          routine to execute from the routine selector, an
  70771.                          integer that’s passed to it in a word on the stack.
  70772.                          The routine selectors for the new routines are as
  70773.                          follows:
  70774.  
  70775.                            scsiReset     .EQU    0
  70776.                            scsiGet       .EQU    1
  70777.                            scsiSelect    .EQU    2
  70778.                            scsiCmd       .EQU    3
  70779.                            scsiComplete  .EQU    4
  70780.                            scsiRead      .EQU    5
  70781.                            scsiWrite     .EQU    6
  70782.                            scsiRBlind    .EQU    8
  70783.                            scsiWBlind    .EQU    9
  70784.                            scsiStat      .EQU    10
  70785.                            scsiSelAtn    .EQU    11
  70786.                            scsiMsgIn     .EQU    12
  70787.                            scsiMsgOut    .EQU    13
  70788.  
  70789. If you specify a routine selector that’s not defined, the System Error Handler is
  70790. called with the system error ID dsCoreErr.
  70791.  
  70792. Most of the SCSI Manager routines return an integer result code of type OSErr. Each
  70793. routine lists all of the applicable result codes, along with a short description of
  70794. what the result code means. Lengthier explanations of all the result codes can be
  70795. found in the summary at the end of this chapter.  The error scSequenceErr is not
  70796. listed under each operation.  It is returned when an attempted operation is out of
  70797. sequence (calling SCSISelect without first calling SCSIGet, for instance).
  70798.  
  70799. Warning:  The error codes returned by SCSI Manager routines typically indicate
  70800.           only that a given operation failed. To determine the actual cause of
  70801.           the failure, you need to send another SCSI command asking the device
  70802.           what went wrong.
  70803.  
  70804. SCSICmd sends the command pointed to by buffer to the selected target device. The
  70805. size of the command in bytes is specified in count.
  70806.  
  70807. Result codes    noErr       No error
  70808.                 commErr     Breakdown in SCSI protocols
  70809.                 phaseErr    Phase error
  70810.  
  70811. æKY SCSIRead
  70812. æFc SCSI.h
  70813. æT Function
  70814. æD pascal OSErr SCSIRead(Ptr tibPtr); 
  70815. æDT OSErr myVariable = SCSIRead((Ptr) tibPtr);
  70816. æRT 96
  70817. æRI IV-290, N96-3
  70818. æC 
  70819. »Assembly-language note:  Unlike most other Operating System routines, the SCSI
  70820.                          Manager routines are stack-based.  You can invoke each
  70821.                          of the SCSI routines with a macro that has the same
  70822.                          name as the routine preceded by an underscore.  These
  70823.                          macros, however, aren’t trap macros themselves;
  70824.                          instead they expand to invoke the trap macro
  70825.                          _SCSIDispatch.  The SCSI Manager determines which
  70826.                          routine to execute from the routine selector, an
  70827.                          integer that’s passed to it in a word on the stack.
  70828.                          The routine selectors for the new routines are as
  70829.                          follows:
  70830.  
  70831.                            scsiReset     .EQU    0
  70832.                            scsiGet       .EQU    1
  70833.                            scsiSelect    .EQU    2
  70834.                            scsiCmd       .EQU    3
  70835.                            scsiComplete  .EQU    4
  70836.                            scsiRead      .EQU    5
  70837.                            scsiWrite     .EQU    6
  70838.                            scsiRBlind    .EQU    8
  70839.                            scsiWBlind    .EQU    9
  70840.                            scsiStat      .EQU    10
  70841.                            scsiSelAtn    .EQU    11
  70842.                            scsiMsgIn     .EQU    12
  70843.                            scsiMsgOut    .EQU    13
  70844.  
  70845. If you specify a routine selector that’s not defined, the System Error Handler is
  70846. called with the system error ID dsCoreErr.
  70847.  
  70848. Most of the SCSI Manager routines return an integer result code of type OSErr. Each
  70849. routine lists all of the applicable result codes, along with a short description of
  70850. what the result code means. Lengthier explanations of all the result codes can be
  70851. found in the summary at the end of this chapter.  The error scSequenceErr is not
  70852. listed under each operation.  It is returned when an attempted operation is out of
  70853. sequence (calling SCSISelect without first calling SCSIGet, for instance).
  70854.  
  70855. Warning:  The error codes returned by SCSI Manager routines typically indicate
  70856.           only that a given operation failed. To determine the actual cause of
  70857.           the failure, you need to send another SCSI command asking the device
  70858.           what went wrong.
  70859.  
  70860. SCSIRead transfers data from the target to the initiator, as specified in the transfer
  70861. instruction block pointed to by tibPtr.
  70862.  
  70863. Result codes    noErr         No error
  70864.                 badParmsErr   Unrecognized instruction in transfer instruction
  70865.                               block
  70866.                 commErr       Breakdown in SCSI protocols
  70867.                 compareErr    Data comparison error (with scComp command
  70868.                               in transfer instruction block)
  70869.                 phaseErr      Phase error
  70870.  
  70871. æKY SCSIRBlind
  70872. æFc SCSI.h
  70873. æT Function
  70874. æD pascal OSErr SCSIRBlind(Ptr tibPtr); 
  70875. æDT OSErr myVariable = SCSIRBlind((Ptr) tibPtr);
  70876. æRT 96
  70877. æRI IV-290, V-574, 576,  N96-3
  70878. æC 
  70879. »Assembly-language note:  Unlike most other Operating System routines, the SCSI
  70880.                          Manager routines are stack-based.  You can invoke each
  70881.                          of the SCSI routines with a macro that has the same
  70882.                          name as the routine preceded by an underscore.  These
  70883.                          macros, however, aren’t trap macros themselves;
  70884.                          instead they expand to invoke the trap macro
  70885.                          _SCSIDispatch.  The SCSI Manager determines which
  70886.                          routine to execute from the routine selector, an
  70887.                          integer that’s passed to it in a word on the stack.
  70888.                          The routine selectors for the new routines are as
  70889.                          follows:
  70890.  
  70891.                            scsiReset     .EQU    0
  70892.                            scsiGet       .EQU    1
  70893.                            scsiSelect    .EQU    2
  70894.                            scsiCmd       .EQU    3
  70895.                            scsiComplete  .EQU    4
  70896.                            scsiRead      .EQU    5
  70897.                            scsiWrite     .EQU    6
  70898.                            scsiRBlind    .EQU    8
  70899.                            scsiWBlind    .EQU    9
  70900.                            scsiStat      .EQU    10
  70901.                            scsiSelAtn    .EQU    11
  70902.                            scsiMsgIn     .EQU    12
  70903.                            scsiMsgOut    .EQU    13
  70904.  
  70905. If you specify a routine selector that’s not defined, the System Error Handler is
  70906. called with the system error ID dsCoreErr.
  70907.  
  70908. Most of the SCSI Manager routines return an integer result code of type OSErr. Each
  70909. routine lists all of the applicable result codes, along with a short description of
  70910. what the result code means. Lengthier explanations of all the result codes can be
  70911. found in the summary at the end of this chapter.  The error scSequenceErr is not
  70912. listed under each operation.  It is returned when an attempted operation is out of
  70913. sequence (calling SCSISelect without first calling SCSIGet, for instance).
  70914.  
  70915. Warning:  The error codes returned by SCSI Manager routines typically indicate
  70916.           only that a given operation failed. To determine the actual cause of
  70917.           the failure, you need to send another SCSI command asking the device
  70918.           what went wrong.
  70919.  
  70920. SCSIRBlind is functionally identical to SCSIRead, but does not poll and wait for the
  70921. /REQ line on each data byte. Rather, the /REQ line is polled only for the first byte
  70922. transferred by each SCINC, SCNOINC, or SCCOMP instruction. For instance, given the
  70923. following transfer instruction block
  70924.  
  70925.   SCINC     $67B50    512
  70926.   SCLOOP    -10       6
  70927.   SCSTOP
  70928.  
  70929. SCSIRBlind polls and waits only for the first byte of each 512-byte block transferred.
  70930.  
  70931. Result codes    noErr          No error
  70932.                 badParmsErr    Unrecognized instruction
  70933.                 commErr        Breakdown in SCSI protocols
  70934.                 compareErr     Data comparison error
  70935.                 phaseErr       Phase error
  70936.                 scBusTOErr     Data not ready within the bus timeout period
  70937.  
  70938. æKY SCSIWrite
  70939. æFc SCSI.h
  70940. æT Function
  70941. æD pascal OSErr SCSIWrite(Ptr tibPtr); 
  70942. æDT OSErr myVariable = SCSIWrite((Ptr) tibPtr);
  70943. æRT 96
  70944. æRI IV-291
  70945. æC 
  70946. »Assembly-language note:  Unlike most other Operating System routines, the SCSI
  70947.                          Manager routines are stack-based.  You can invoke each
  70948.                          of the SCSI routines with a macro that has the same
  70949.                          name as the routine preceded by an underscore.  These
  70950.                          macros, however, aren’t trap macros themselves;
  70951.                          instead they expand to invoke the trap macro
  70952.                          _SCSIDispatch.  The SCSI Manager determines which
  70953.                          routine to execute from the routine selector, an
  70954.                          integer that’s passed to it in a word on the stack.
  70955.                          The routine selectors for the new routines are as
  70956.                          follows:
  70957.  
  70958.                            scsiReset     .EQU    0
  70959.                            scsiGet       .EQU    1
  70960.                            scsiSelect    .EQU    2
  70961.                            scsiCmd       .EQU    3
  70962.                            scsiComplete  .EQU    4
  70963.                            scsiRead      .EQU    5
  70964.                            scsiWrite     .EQU    6
  70965.                            scsiRBlind    .EQU    8
  70966.                            scsiWBlind    .EQU    9
  70967.                            scsiStat      .EQU    10
  70968.                            scsiSelAtn    .EQU    11
  70969.                            scsiMsgIn     .EQU    12
  70970.                            scsiMsgOut    .EQU    13
  70971.  
  70972. If you specify a routine selector that’s not defined, the System Error Handler is
  70973. called with the system error ID dsCoreErr.
  70974.  
  70975. Most of the SCSI Manager routines return an integer result code of type OSErr. Each
  70976. routine lists all of the applicable result codes, along with a short description of
  70977. what the result code means. Lengthier explanations of all the result codes can be
  70978. found in the summary at the end of this chapter.  The error scSequenceErr is not
  70979. listed under each operation.  It is returned when an attempted operation is out of
  70980. sequence (calling SCSISelect without first calling SCSIGet, for instance).
  70981.  
  70982. Warning:  The error codes returned by SCSI Manager routines typically indicate
  70983.           only that a given operation failed. To determine the actual cause of
  70984.           the failure, you need to send another SCSI command asking the device
  70985.           what went wrong.
  70986.  
  70987. SCSIWrite transfers data from the initiator to the target, as specified in the command
  70988. descriptor block pointed to by tibPtr.
  70989.  
  70990. Result codes    noErr          No error
  70991.                 badParmsErr    Unrecognized instruction
  70992.                 commErr        Breakdown in SCSI protocols
  70993.                 phaseErr       Phase error
  70994.  
  70995. æKY SCSIWBlind
  70996. æFc SCSI.h
  70997. æT Function
  70998. æD pascal OSErr SCSIWBlind(Ptr tibPtr); 
  70999. æDT OSErr myVariable = SCSIWBlind((Ptr) tibPtr);
  71000. æRT 96
  71001. æRI IV-291, V-574, 576
  71002. æC 
  71003. »Assembly-language note:  Unlike most other Operating System routines, the SCSI
  71004.                          Manager routines are stack-based.  You can invoke each
  71005.                          of the SCSI routines with a macro that has the same
  71006.                          name as the routine preceded by an underscore.  These
  71007.                          macros, however, aren’t trap macros themselves;
  71008.                          instead they expand to invoke the trap macro
  71009.                          _SCSIDispatch.  The SCSI Manager determines which
  71010.                          routine to execute from the routine selector, an
  71011.                          integer that’s passed to it in a word on the stack.
  71012.                          The routine selectors for the new routines are as
  71013.                          follows:
  71014.  
  71015.                            scsiReset     .EQU    0
  71016.                            scsiGet       .EQU    1
  71017.                            scsiSelect    .EQU    2
  71018.                            scsiCmd       .EQU    3
  71019.                            scsiComplete  .EQU    4
  71020.                            scsiRead      .EQU    5
  71021.                            scsiWrite     .EQU    6
  71022.                            scsiRBlind    .EQU    8
  71023.                            scsiWBlind    .EQU    9
  71024.                            scsiStat      .EQU    10
  71025.                            scsiSelAtn    .EQU    11
  71026.                            scsiMsgIn     .EQU    12
  71027.                            scsiMsgOut    .EQU    13
  71028.  
  71029. If you specify a routine selector that’s not defined, the System Error Handler is
  71030. called with the system error ID dsCoreErr.
  71031.  
  71032. Most of the SCSI Manager routines return an integer result code of type OSErr. Each
  71033. routine lists all of the applicable result codes, along with a short description of
  71034. what the result code means. Lengthier explanations of all the result codes can be
  71035. found in the summary at the end of this chapter.  The error scSequenceErr is not
  71036. listed under each operation.  It is returned when an attempted operation is out of
  71037. sequence (calling SCSISelect without first calling SCSIGet, for instance).
  71038.  
  71039. Warning:  The error codes returned by SCSI Manager routines typically indicate
  71040.           only that a given operation failed. To determine the actual cause of
  71041.           the failure, you need to send another SCSI command asking the device
  71042.           what went wrong.
  71043.  
  71044. SCSIWBlind is functionally identical to SCSIWrite, but does not poll and wait for the
  71045. /REQ line on each data byte. As with SCSIRBlind, SCSIWBlind polls the
  71046. /REQ line only for the first byte transferred by each SCINC, SCNOINC, or SCCOMP
  71047. instruction.
  71048.  
  71049. Result codes    noErr          No error
  71050.                 badParmsErr    Unrecognized instruction
  71051.                 commErr        Breakdown in SCSI protocols
  71052.                 phaseErr       Phase error
  71053.                 scBusTOErr     Data not ready within the bus timeout period
  71054.  
  71055. æKY SCSIComplete
  71056. æFc SCSI.h
  71057. æT Function
  71058. æD pascal OSErr SCSIComplete(short *stat,short *message,unsigned long wait); 
  71059. æDT OSErr myVariable = SCSIComplete((short *) stat,(short *) message,(unsigned long) wait);
  71060. æRT 96
  71061. æRI IV-291, N96-3
  71062. æC 
  71063. »Assembly-language note:  Unlike most other Operating System routines, the SCSI
  71064.                          Manager routines are stack-based.  You can invoke each
  71065.                          of the SCSI routines with a macro that has the same
  71066.                          name as the routine preceded by an underscore.  These
  71067.                          macros, however, aren’t trap macros themselves;
  71068.                          instead they expand to invoke the trap macro
  71069.                          _SCSIDispatch.  The SCSI Manager determines which
  71070.                          routine to execute from the routine selector, an
  71071.                          integer that’s passed to it in a word on the stack.
  71072.                          The routine selectors for the new routines are as
  71073.                          follows:
  71074.  
  71075.                            scsiReset     .EQU    0
  71076.                            scsiGet       .EQU    1
  71077.                            scsiSelect    .EQU    2
  71078.                            scsiCmd       .EQU    3
  71079.                            scsiComplete  .EQU    4
  71080.                            scsiRead      .EQU    5
  71081.                            scsiWrite     .EQU    6
  71082.                            scsiRBlind    .EQU    8
  71083.                            scsiWBlind    .EQU    9
  71084.                            scsiStat      .EQU    10
  71085.                            scsiSelAtn    .EQU    11
  71086.                            scsiMsgIn     .EQU    12
  71087.                            scsiMsgOut    .EQU    13
  71088.  
  71089. If you specify a routine selector that’s not defined, the System Error Handler is
  71090. called with the system error ID dsCoreErr.
  71091.  
  71092. Most of the SCSI Manager routines return an integer result code of type OSErr. Each
  71093. routine lists all of the applicable result codes, along with a short description of
  71094. what the result code means. Lengthier explanations of all the result codes can be
  71095. found in the summary at the end of this chapter.  The error scSequenceErr is not
  71096. listed under each operation.  It is returned when an attempted operation is out of
  71097. sequence (calling SCSISelect without first calling SCSIGet, for instance).
  71098.  
  71099. Warning:  The error codes returned by SCSI Manager routines typically indicate
  71100.           only that a given operation failed. To determine the actual cause of
  71101.           the failure, you need to send another SCSI command asking the device
  71102.           what went wrong.
  71103.  
  71104. SCSIComplete gives the current command wait number of ticks to complete; the two
  71105. completion bytes are returned in stat and message.
  71106.  
  71107. Result codes    noErr              No error
  71108.                 commErr            Breakdown in SCSI protocols
  71109.                 phaseErr           Phase error
  71110.                 scComplPhaseErr    Bus not in the Status phase (indicates
  71111.                                    that either filler bytes were written or
  71112.                                    bytes were read and lost)
  71113.  
  71114. æKY SCSIStat
  71115. æFc SCSI.h
  71116. æT Function
  71117. æD pascal short SCSIStat(void); 
  71118. æDT short myVariable = SCSIStat()(void);
  71119. æRT 96
  71120. æRI IV-291, N96-2, 4
  71121. æC 
  71122. »Assembly-language note:  Unlike most other Operating System routines, the SCSI
  71123.                          Manager routines are stack-based.  You can invoke each
  71124.                          of the SCSI routines with a macro that has the same
  71125.                          name as the routine preceded by an underscore.  These
  71126.                          macros, however, aren’t trap macros themselves;
  71127.                          instead they expand to invoke the trap macro
  71128.                          _SCSIDispatch.  The SCSI Manager determines which
  71129.                          routine to execute from the routine selector, an
  71130.                          integer that’s passed to it in a word on the stack.
  71131.                          The routine selectors for the new routines are as
  71132.                          follows:
  71133.  
  71134.                            scsiReset     .EQU    0
  71135.                            scsiGet       .EQU    1
  71136.                            scsiSelect    .EQU    2
  71137.                            scsiCmd       .EQU    3
  71138.                            scsiComplete  .EQU    4
  71139.                            scsiRead      .EQU    5
  71140.                            scsiWrite     .EQU    6
  71141.                            scsiRBlind    .EQU    8
  71142.                            scsiWBlind    .EQU    9
  71143.                            scsiStat      .EQU    10
  71144.                            scsiSelAtn    .EQU    11
  71145.                            scsiMsgIn     .EQU    12
  71146.                            scsiMsgOut    .EQU    13
  71147.  
  71148. If you specify a routine selector that’s not defined, the System Error Handler is
  71149. called with the system error ID dsCoreErr.
  71150.  
  71151. Most of the SCSI Manager routines return an integer result code of type OSErr. Each
  71152. routine lists all of the applicable result codes, along with a short description of
  71153. what the result code means. Lengthier explanations of all the result codes can be
  71154. found in the summary at the end of this chapter.  The error scSequenceErr is not
  71155. listed under each operation.  It is returned when an attempted operation is out of
  71156. sequence (calling SCSISelect without first calling SCSIGet, for instance).
  71157.  
  71158. Warning:  The error codes returned by SCSI Manager routines typically indicate
  71159.           only that a given operation failed. To determine the actual cause of
  71160.           the failure, you need to send another SCSI command asking the device
  71161.           what went wrong.
  71162.  
  71163. This function returns a bit map of SCSI control and status bits; these bits are shown
  71164. in Figure 1. See the NCR 5380 SCSI chip documentation for a description of these
  71165. signals. (Bits 0–9 are complements of the SCSI bus standard signals.)
  71166.  
  71167. Result codes    noErr       No error
  71168.                 commErr     Breakdown in SCSI protocols
  71169.                 phaseErr    Phase error
  71170.  
  71171. •••Refer to Figure 1.•••
  71172.  
  71173. Figure 1–SCSI Control and Status Bits
  71174.  
  71175. æKY SCSISelAtn
  71176. æFc SCSI.h
  71177. æT Function
  71178. æD pascal OSErr SCSISelAtn(short targetID); 
  71179. æDT OSErr myVariable = SCSISelAtn((short) targetID);
  71180. æRI V-575
  71181. æC 
  71182. »Assembly-language note:  Unlike most other Operating System routines, the SCSI
  71183.                          Manager routines are stack-based.  You can invoke each
  71184.                          of the SCSI routines with a macro that has the same
  71185.                          name as the routine preceded by an underscore.  These
  71186.                          macros, however, aren’t trap macros themselves;
  71187.                          instead they expand to invoke the trap macro
  71188.                          _SCSIDispatch.  The SCSI Manager determines which
  71189.                          routine to execute from the routine selector, an
  71190.                          integer that’s passed to it in a word on the stack.
  71191.                          The routine selectors for the new routines are as
  71192.                          follows:
  71193.  
  71194.                            scsiReset     .EQU    0
  71195.                            scsiGet       .EQU    1
  71196.                            scsiSelect    .EQU    2
  71197.                            scsiCmd       .EQU    3
  71198.                            scsiComplete  .EQU    4
  71199.                            scsiRead      .EQU    5
  71200.                            scsiWrite     .EQU    6
  71201.                            scsiRBlind    .EQU    8
  71202.                            scsiWBlind    .EQU    9
  71203.                            scsiStat      .EQU    10
  71204.                            scsiSelAtn    .EQU    11
  71205.                            scsiMsgIn     .EQU    12
  71206.                            scsiMsgOut    .EQU    13
  71207.  
  71208. If you specify a routine selector that’s not defined, the System Error Handler is
  71209. called with the system error ID dsCoreErr.
  71210.  
  71211. Most of the SCSI Manager routines return an integer result code of type OSErr. Each
  71212. routine lists all of the applicable result codes, along with a short description of
  71213. what the result code means. Lengthier explanations of all the result codes can be
  71214. found in the summary at the end of this chapter.  The error scSequenceErr is not
  71215. listed under each operation.  It is returned when an attempted operation is out of
  71216. sequence (calling SCSISelect without first calling SCSIGet, for instance).
  71217.  
  71218. Warning:  The error codes returned by SCSI Manager routines typically indicate
  71219.           only that a given operation failed. To determine the actual cause of
  71220.           the failure, you need to send another SCSI command asking the device
  71221.           what went wrong.
  71222.  
  71223. SCSISelAtn is identical in function to SCSISelect except that it asserts the Attention
  71224. line during selection, signaling that you want to send a message to the device.
  71225.  
  71226. æKY SCSIMsgIn
  71227. æFc SCSI.h
  71228. æT Function
  71229. æD pascal OSErr SCSIMsgIn(short *message); 
  71230. æDT OSErr myVariable = SCSIMsgIn((short *) message);
  71231. æRI V-575
  71232. æC 
  71233. »Assembly-language note:  Unlike most other Operating System routines, the SCSI
  71234.                          Manager routines are stack-based.  You can invoke each
  71235.                          of the SCSI routines with a macro that has the same
  71236.                          name as the routine preceded by an underscore.  These
  71237.                          macros, however, aren’t trap macros themselves;
  71238.                          instead they expand to invoke the trap macro
  71239.                          _SCSIDispatch.  The SCSI Manager determines which
  71240.                          routine to execute from the routine selector, an
  71241.                          integer that’s passed to it in a word on the stack.
  71242.                          The routine selectors for the new routines are as
  71243.                          follows:
  71244.  
  71245.                            scsiReset     .EQU    0
  71246.                            scsiGet       .EQU    1
  71247.                            scsiSelect    .EQU    2
  71248.                            scsiCmd       .EQU    3
  71249.                            scsiComplete  .EQU    4
  71250.                            scsiRead      .EQU    5
  71251.                            scsiWrite     .EQU    6
  71252.                            scsiRBlind    .EQU    8
  71253.                            scsiWBlind    .EQU    9
  71254.                            scsiStat      .EQU    10
  71255.                            scsiSelAtn    .EQU    11
  71256.                            scsiMsgIn     .EQU    12
  71257.                            scsiMsgOut    .EQU    13
  71258.  
  71259. If you specify a routine selector that’s not defined, the System Error Handler is
  71260. called with the system error ID dsCoreErr.
  71261.  
  71262. Most of the SCSI Manager routines return an integer result code of type OSErr. Each
  71263. routine lists all of the applicable result codes, along with a short description of
  71264. what the result code means. Lengthier explanations of all the result codes can be
  71265. found in the summary at the end of this chapter.  The error scSequenceErr is not
  71266. listed under each operation.  It is returned when an attempted operation is out of
  71267. sequence (calling SCSISelect without first calling SCSIGet, for instance).
  71268.  
  71269. Warning:  The error codes returned by SCSI Manager routines typically indicate
  71270.           only that a given operation failed. To determine the actual cause of
  71271.           the failure, you need to send another SCSI command asking the device
  71272.           what went wrong.
  71273.  
  71274. SCSIMsgIn gets a message from the device.  The message is contained in the low-order
  71275. byte of the message parameter; message values are listed in the ANSI documentation
  71276. for SCSI.
  71277.  
  71278. SCSIMsgIn leaves the Attention line undisturbed if it’s already asserted upon entry.
  71279.  
  71280. æKY SCSIMsgOut
  71281. æFc SCSI.h
  71282. æT Function
  71283. æD pascal OSErr SCSIMsgOut(short message); 
  71284. æDT OSErr myVariable = SCSIMsgOut((short) message);
  71285. æRI V-575
  71286. æC 
  71287. »Assembly-language note:  Unlike most other Operating System routines, the SCSI
  71288.                          Manager routines are stack-based.  You can invoke each
  71289.                          of the SCSI routines with a macro that has the same
  71290.                          name as the routine preceded by an underscore.  These
  71291.                          macros, however, aren’t trap macros themselves;
  71292.                          instead they expand to invoke the trap macro
  71293.                          _SCSIDispatch.  The SCSI Manager determines which
  71294.                          routine to execute from the routine selector, an
  71295.                          integer that’s passed to it in a word on the stack.
  71296.                          The routine selectors for the new routines are as
  71297.                          follows:
  71298.  
  71299.                            scsiReset     .EQU    0
  71300.                            scsiGet       .EQU    1
  71301.                            scsiSelect    .EQU    2
  71302.                            scsiCmd       .EQU    3
  71303.                            scsiComplete  .EQU    4
  71304.                            scsiRead      .EQU    5
  71305.                            scsiWrite     .EQU    6
  71306.                            scsiRBlind    .EQU    8
  71307.                            scsiWBlind    .EQU    9
  71308.                            scsiStat      .EQU    10
  71309.                            scsiSelAtn    .EQU    11
  71310.                            scsiMsgIn     .EQU    12
  71311.                            scsiMsgOut    .EQU    13
  71312.  
  71313. If you specify a routine selector that’s not defined, the System Error Handler is
  71314. called with the system error ID dsCoreErr.
  71315.  
  71316. Most of the SCSI Manager routines return an integer result code of type OSErr. Each
  71317. routine lists all of the applicable result codes, along with a short description of
  71318. what the result code means. Lengthier explanations of all the result codes can be
  71319. found in the summary at the end of this chapter.  The error scSequenceErr is not
  71320. listed under each operation.  It is returned when an attempted operation is out of
  71321. sequence (calling SCSISelect without first calling SCSIGet, for instance).
  71322.  
  71323. Warning:  The error codes returned by SCSI Manager routines typically indicate
  71324.           only that a given operation failed. To determine the actual cause of
  71325.           the failure, you need to send another SCSI command asking the device
  71326.           what went wrong.
  71327.  
  71328. SCSIMsgOut sends a message byte to the target device; message values are listed in
  71329. the ANSI documentation for SCSI.
  71330.  
  71331.  
  71332. æKY SegLoad.h
  71333. æKL ClrAppFiles
  71334. CountAppFiles
  71335. ExitToShell
  71336. GetAppFiles
  71337. getappparms
  71338. GetAppParms
  71339. UnloadSeg
  71340.  
  71341. AppFile
  71342. appOpen
  71343. appPrint
  71344.  
  71345. æKY appOpen
  71346. æFc SegLoad.h
  71347. æT #define
  71348. æD #define appOpen 0 /*Open the Document (s)*/
  71349. æC 
  71350.  
  71351. æKY appPrint
  71352. æFc SegLoad.h
  71353. æT #define
  71354. æD #define appPrint 1 /*Print the Document (s)*/
  71355. æC 
  71356.  
  71357. æKY AppFile
  71358. æFc SegLoad.h
  71359. æT struct
  71360. æD struct AppFile {
  71361.     short vRefNum;
  71362.     OSType fType;
  71363.     short versNum; /*versNum in high byte*/
  71364.     Str255 fName;
  71365. };
  71366.  
  71367. typedef struct AppFile AppFile;
  71368. æC 
  71369.  
  71370. æKY UnloadSeg
  71371. æFc SegLoad.h
  71372. æT Function
  71373. æTN A9F1
  71374. æD 
  71375. pascal void UnloadSeg(void * routineAddr)
  71376.     = 0xA9F1; 
  71377. æDT 
  71378. UnloadSeg((void *) routineAddr);
  71379. æMM
  71380. æRI II-59, N39-1, P-56, 184
  71381. æC 
  71382. UnloadSeg unloads a segment, making it relocatable and purgeable; routineAddr is the
  71383. address of any externally referenced routine in the segment. The segment won’t actually
  71384. be purged until the memory it occupies is needed. If the segment is purged, the
  71385. Segment Loader will reload it the next time one of the routines in it is called.
  71386.  
  71387. Note:  UnloadSeg will work only if called from outside the segment to be
  71388.        unloaded.
  71389.  
  71390. æKY ExitToShell
  71391. æFc SegLoad.h
  71392. æT Function
  71393. æTN A9F4
  71394. æD pascal void ExitToShell(void)
  71395.     = 0xA9F4; 
  71396. æDT ExitToShell()(void);
  71397. æMM
  71398. æRI II-59, N64-1
  71399. æC 
  71400. ExitToShell provides an exit from an application by starting up the Finder
  71401. (after releasing the entire application heap).
  71402.  
  71403. Assembly-language note:  ExitToShell actually launches the application whose
  71404.                          name is stored in the global variable FinderName.
  71405.  
  71406. æKY GetAppParms
  71407. æFc SegLoad.h
  71408. æT Function
  71409. æTN A9F5
  71410. æD pascal void GetAppParms(Str255 apName,short *apRefNum,Handle *apParam)
  71411.     = 0xA9F5; 
  71412. æDT GetAppParms((Str255) apName,(short *) apRefNum,(Handle *) apParam);
  71413. æRI II-58
  71414. æC 
  71415. GetAppParms returns information about the current application. It returns the application
  71416. name in apName and the reference number for the application’s resource file in apRefNum.
  71417. A handle to the Finder information is returned in apParam, but the Finder information
  71418. is more easily accessed with the GetAppFiles call.
  71419.  
  71420. Assembly-language note:  Assembly-language programmers can instead get the
  71421.                          application name, reference number, and handle to the
  71422.                          Finder information directly from the global variables
  71423.                          CurApName, CurApRefNum, and AppParmHandle.
  71424.  
  71425. Note:  If you simply want the application’s resource file reference number,
  71426.        you can call the Resource Manager function CurResFile when the
  71427.        application starts up.
  71428.  
  71429. æKY CountAppFiles
  71430. æFc SegLoad.h
  71431. æT Function
  71432. æD pascal void CountAppFiles(short *message,short *count); 
  71433. æDT CountAppFiles((short *) message,(short *) count);
  71434. æRI II-57
  71435. æC 
  71436. [Not in ROM]
  71437.  
  71438. CountAppFiles deciphers the Finder information passed to your application, and returns
  71439. information about the documents that were selected when your application started up.
  71440. It returns the number of selected documents in the count parameter, and a number in
  71441. the message parameter that indicates whether the documents are to opened or printed:
  71442.  
  71443. CONST  appOpen  = 0;  {open the document(s)}
  71444.        appPrint = 1;  {print the document(s)}
  71445.  
  71446. Assembly-language note:  Instead of using CountAppFiles, GetAppFiles, and
  71447.                          ClrAppFiles, assembly-language programmers can access
  71448.                          the Finder information via the global variable
  71449.                          AppParmHandle, which contains a handle to the Finder
  71450.                          information. Parse the Finder information as shown in
  71451.                          Figure 1 above. For each document that your
  71452.                          application opens or prints, set the file type in the
  71453.                          Finder information to 0.
  71454.  
  71455. æKY GetAppFiles
  71456. æFc SegLoad.h
  71457. æT Function
  71458. æD pascal void GetAppFiles(short index,AppFile *theFile); 
  71459. æDT GetAppFiles((short) index,(AppFile *) theFile);
  71460. æRT 77
  71461. æRI II-58, N77-2
  71462. æC 
  71463. [Not in ROM]
  71464.  
  71465. GetAppFiles returns information about a document that was selected when your application
  71466. started up (as listed in the Finder information). The index parameter indicates the
  71467. file for which information should be returned; it must be between 1 and the number
  71468. returned by CountAppFiles, inclusive. The information is returned in the following
  71469. data structure:
  71470.  
  71471. TYPE  AppFile = RECORD
  71472.                   vRefNum:  INTEGER;    {volume reference number}
  71473.                   fType:    OSType;     {file type}
  71474.                   versNum:  INTEGER;    {version number}
  71475.                   fName:    Str255      {file name}
  71476.                 END;
  71477.  
  71478. Assembly-language note:  Instead of using CountAppFiles, GetAppFiles, and
  71479.                          ClrAppFiles, assembly-language programmers can access
  71480.                          the Finder information via the global variable
  71481.                          AppParmHandle, which contains a handle to the Finder
  71482.                          information. Parse the Finder information as shown in
  71483.                          Figure 1 above. For each document that your
  71484.                          application opens or prints, set the file type in the
  71485.                          Finder information to 0.
  71486.  
  71487. æKY ClrAppFiles
  71488. æFc SegLoad.h
  71489. æT Function
  71490. æD pascal void ClrAppFiles(short index); 
  71491. æDT ClrAppFiles((short) index);
  71492. æRI II-58
  71493. æC 
  71494. [Not in ROM]
  71495.  
  71496. ClrAppFiles changes the Finder information passed to your application about the
  71497. specified file such that the Finder knows you’ve processed the file. The index parameter
  71498. must be between 1 and the number returned by CountAppFiles. You should call ClrAppFiles
  71499. for every document your application opens or prints, so that the information returned
  71500. by CountAppFiles and GetAppFiles is always correct. (ClrAppFiles sets the file type
  71501. in the Finder information to 0.)
  71502.  
  71503. Assembly-language note:  Instead of using CountAppFiles, GetAppFiles, and
  71504.                          ClrAppFiles, assembly-language programmers can access
  71505.                          the Finder information via the global variable
  71506.                          AppParmHandle, which contains a handle to the Finder
  71507.                          information. Parse the Finder information as shown in
  71508.                          Figure 1 above. For each document that your
  71509.                          application opens or prints, set the file type in the
  71510.                          Finder information to 0.
  71511.  
  71512. æKY getappparms
  71513. æFc SegLoad.h
  71514. æT Function
  71515. æD void getappparms(char *apName,short *apRefNum,Handle *apParam); 
  71516. æDT getappparms((char *) apName,(short *) apRefNum,(Handle *) apParam);
  71517. æRI II-58
  71518. æC 
  71519. GetAppParms returns information about the current application. It returns the application
  71520. name in apName and the reference number for the application’s resource file in apRefNum.
  71521. A handle to the Finder information is returned in apParam, but the Finder information
  71522. is more easily accessed with the GetAppFiles call.
  71523.  
  71524. Assembly-language note:  Assembly-language programmers can instead get the
  71525.                          application name, reference number, and handle to the
  71526.                          Finder information directly from the global variables
  71527.                          CurApName, CurApRefNum, and AppParmHandle.
  71528.  
  71529. Note:  If you simply want the application’s resource file reference number,
  71530.        you can call the Resource Manager function CurResFile when the
  71531.        application starts up.
  71532.  
  71533.  
  71534. æKY Serial.h
  71535. æKL RAMSDClose
  71536. RAMSDOpen
  71537. SerClrBrk
  71538. SerGetBuf
  71539. SerHShake
  71540. SerReset
  71541. SerSetBrk
  71542. SerSetBuf
  71543. SerStatus
  71544.  
  71545. ainRefNum
  71546. aoutRefNum
  71547. baud1200
  71548. baud1800
  71549. baud19200
  71550. baud2400
  71551. baud300
  71552. baud3600
  71553. baud4800
  71554. baud57600
  71555. baud600
  71556. baud7200
  71557. baud9600
  71558. binRefNum
  71559. boutRefNum
  71560. breakEvent
  71561. ctsEvent
  71562. data5
  71563. data6
  71564. data7
  71565. data8
  71566. dtrNegated
  71567. evenParity
  71568. noParity
  71569. oddParity
  71570. SerShk
  71571. SerStaRec
  71572. sPortA
  71573. sPortB
  71574. SPortSel
  71575. stop10
  71576. stop15
  71577. stop20
  71578. xOffWasSent
  71579.  
  71580. æKY baud300
  71581. æFc Serial.h
  71582. æT #define
  71583. æD #define baud300 380
  71584. æC 
  71585.  
  71586. æKY baud600
  71587. æFc Serial.h
  71588. æT #define
  71589. æD #define baud600 189
  71590. æC 
  71591.  
  71592. æKY baud1200
  71593. æFc Serial.h
  71594. æT #define
  71595. æD #define baud1200 94
  71596. æC 
  71597.  
  71598. æKY baud1800
  71599. æFc Serial.h
  71600. æT #define
  71601. æD #define baud1800 62
  71602. æC 
  71603.  
  71604. æKY baud2400
  71605. æFc Serial.h
  71606. æT #define
  71607. æD #define baud2400 46
  71608. æC 
  71609.  
  71610. æKY baud3600
  71611. æFc Serial.h
  71612. æT #define
  71613. æD #define baud3600 30
  71614. æC 
  71615.  
  71616. æKY baud4800
  71617. æFc Serial.h
  71618. æT #define
  71619. æD #define baud4800 22
  71620. æC 
  71621.  
  71622. æKY baud7200
  71623. æFc Serial.h
  71624. æT #define
  71625. æD #define baud7200 14
  71626. æC 
  71627.  
  71628. æKY baud9600
  71629. æFc Serial.h
  71630. æT #define
  71631. æD #define baud9600 10
  71632. æC 
  71633.  
  71634. æKY baud19200
  71635. æFc Serial.h
  71636. æT #define
  71637. æD #define baud19200 4
  71638. æC 
  71639.  
  71640. æKY baud57600
  71641. æFc Serial.h
  71642. æT #define
  71643. æD #define baud57600 0
  71644. æC 
  71645.  
  71646. æKY stop10
  71647. æFc Serial.h
  71648. æT #define
  71649. æD #define stop10 16384
  71650. æC 
  71651.  
  71652. æKY stop15
  71653. æFc Serial.h
  71654. æT #define
  71655. æD #define stop15 -32768
  71656. æC 
  71657.  
  71658. æKY stop20
  71659. æFc Serial.h
  71660. æT #define
  71661. æD #define stop20 -16384
  71662. æC 
  71663.  
  71664. æKY noParity
  71665. æFc Serial.h
  71666. æT #define
  71667. æD #define noParity 0
  71668. æC 
  71669.  
  71670. æKY oddParity
  71671. æFc Serial.h
  71672. æT #define
  71673. æD #define oddParity 4096
  71674. æC 
  71675.  
  71676. æKY evenParity
  71677. æFc Serial.h
  71678. æT #define
  71679. æD #define evenParity 12288
  71680. æC 
  71681.  
  71682. æKY data5
  71683. æFc Serial.h
  71684. æT #define
  71685. æD #define data5 0
  71686. æC 
  71687.  
  71688. æKY data6
  71689. æFc Serial.h
  71690. æT #define
  71691. æD #define data6 2048
  71692. æC 
  71693.  
  71694. æKY data7
  71695. æFc Serial.h
  71696. æT #define
  71697. æD #define data7 1024
  71698. æC 
  71699.  
  71700. æKY data8
  71701. æFc Serial.h
  71702. æT #define
  71703. æD #define data8 3072
  71704. æC 
  71705.  
  71706. æKY ctsEvent
  71707. æFc Serial.h
  71708. æT #define
  71709. æD #define ctsEvent 32
  71710. æC 
  71711.  
  71712. æKY breakEvent
  71713. æFc Serial.h
  71714. æT #define
  71715. æD #define breakEvent 128
  71716. æC 
  71717.  
  71718. æKY xOffWasSent
  71719. æFc Serial.h
  71720. æT #define
  71721. æD #define xOffWasSent 128
  71722. æC 
  71723.  
  71724. æKY dtrNegated
  71725. æFc Serial.h
  71726. æT #define
  71727. æD #define dtrNegated 64
  71728. æC 
  71729.  
  71730. æKY ainRefNum
  71731. æFc Serial.h
  71732. æT #define
  71733. æD #define ainRefNum -6 /*serial port A input*/
  71734. æC 
  71735.  
  71736. æKY aoutRefNum
  71737. æFc Serial.h
  71738. æT #define
  71739. æD #define aoutRefNum -7 /*serial port A output*/
  71740. æC 
  71741.  
  71742. æKY binRefNum
  71743. æFc Serial.h
  71744. æT #define
  71745. æD #define binRefNum -8 /*serial port B input*/
  71746. æC 
  71747.  
  71748. æKY boutRefNum
  71749. æFc Serial.h
  71750. æT #define
  71751. æD #define boutRefNum -9 /*serial port B output*/
  71752. æC 
  71753.  
  71754. æKY SPortSel
  71755. sPortA
  71756. sPortB
  71757. æFc Serial.h
  71758. æT enum
  71759. æD enum {sPortA,sPortB};
  71760. typedef unsigned char SPortSel;
  71761. æC 
  71762.  
  71763. æKY SerShk
  71764. æFc Serial.h
  71765. æT struct
  71766. æD struct SerShk {
  71767.     char fXOn; /*XOn flow control enabled flag*/
  71768.     char fCTS; /*CTS flow control enabled flag*/
  71769.     unsigned char xOn; /*XOn character*/
  71770.     unsigned char xOff; /*XOff character*/
  71771.     char errs; /*errors mask bits*/
  71772.     char evts; /*event enable mask bits*/
  71773.     char fInX; /*Input flow control enabled flag*/
  71774.     char fDTR; /*DTR input flow control flag*/
  71775. };
  71776.  
  71777. typedef struct SerShk SerShk;
  71778. æC 
  71779.  
  71780. æKY SerStaRec
  71781. æFc Serial.h
  71782. æT struct
  71783. æD struct SerStaRec {
  71784.     char cumErrs;
  71785.     char xOffSent;
  71786.     char rdPend;
  71787.     char wrPend;
  71788.     char ctsHold;
  71789.     char xOffHold;
  71790. };
  71791.  
  71792. typedef struct SerStaRec SerStaRec;
  71793. æC 
  71794.  
  71795. æKY RAMSDOpen
  71796. æFc Serial.h
  71797. æT Function
  71798. æD pascal OSErr RAMSDOpen(SPortSel whichPort); 
  71799. æDT OSErr myVariable = RAMSDOpen((SPortSel) whichPort);
  71800. æRI II-249
  71801. æC 
  71802.  
  71803. æKY RAMSDClose
  71804. æFc Serial.h
  71805. æT Function
  71806. æD pascal void RAMSDClose(SPortSel whichPort); 
  71807. æDT RAMSDClose((SPortSel) whichPort);
  71808. æRI II-250
  71809. æC 
  71810.  
  71811. æKY SerReset
  71812. æFc Serial.h
  71813. æT Function
  71814. æD pascal OSErr SerReset(short refNum,short serConfig); 
  71815. æDT OSErr myVariable = SerReset((short) refNum,(short) serConfig);
  71816. æMM
  71817. æRI II-250
  71818. æC 
  71819. [Not in ROM]
  71820.  
  71821. Assembly-language note:  SerReset is equivalent to a Control call with
  71822.                          csCode=8 and csParam=serConfig.
  71823.  
  71824. SerReset resets and reinitializes the input or output driver having the reference
  71825. number refNum according to the information in serConfig. Figure 3 shows the format of
  71826. serConfig.
  71827.  
  71828. •••Refer to Figure 3.•••
  71829.  
  71830. Figure 3–Driver Reset Information
  71831.  
  71832. You can use the following predefined constants to set the values of various bits of
  71833. serConfig:
  71834.  
  71835. CONST  baud300    =    380;    {300 baud}
  71836.        baud600    =    189;    {600 baud}
  71837.        baud1200   =     94;    {1200 baud}
  71838.        baud1800   =     62;    {1800 baud}
  71839.        baud2400   =     46;    {2400 baud}
  71840.        baud3600   =     30;    {3600 baud}
  71841.        baud4800   =     22;    {4800 baud}
  71842.        baud7200   =     14;    {7200 baud}
  71843.        baud9600   =     10;    {9600 baud}
  71844.        baud19200  =      4;    {19200 baud}
  71845.        baud57600  =      0;    {57600 baud}
  71846.        stop10     =  16384;    {1 stop bit}
  71847.        stop15     = -32768;    {1.5 stop bits}
  71848.        stop20     = -16384;    {2 stop bits}
  71849.        noParity   =      0;    {no parity}
  71850.        oddParity  =   4096;    {odd parity}
  71851.        evenParity =  12288;    {even parity}
  71852.        data5      =      0;    {5 data bits}
  71853.        data6      =   2048;    {6 data bits}
  71854.        data7      =   1024;    {7 data bits}
  71855.        data8      =   3072;    {8 data bits}
  71856.  
  71857. For example, the default setting of 9600 baud, eight data bits, two stop bits, and no
  71858. parity bit is equivalent to passing the following value in serConfig:  baud9600 +
  71859. data8 + stop20 + noParity.
  71860.  
  71861. Result codes    noErr    No error
  71862.  
  71863. æKY SerSetBuf
  71864. æFc Serial.h
  71865. æT Function
  71866. æD pascal OSErr SerSetBuf(short refNum,Ptr serBPtr,short serBLen); 
  71867. æDT OSErr myVariable = SerSetBuf((short) refNum,(Ptr) serBPtr,(short) serBLen);
  71868. æMM
  71869. æRI II-251
  71870. æC 
  71871. [Not in ROM]
  71872.  
  71873. Assembly-language note:  SerSetBuf is equivalent to a Control call with
  71874.                          csCode=9, csParam=serBPtr, and csParam+4=serBLen.
  71875.  
  71876. SerSetBuf specifies a new input buffer for the input driver having the reference
  71877. number refNum. SerBPtr points to the buffer, and serBLen specifies the number of
  71878. bytes in the buffer. To restore the driver’s default buffer, call SerSetBuf with
  71879. serBLen set to 0.
  71880.  
  71881. Warning:  You must lock a new input buffer while it’s in use.
  71882.  
  71883. Result codes    noErr    No error
  71884.  
  71885. æKY SerHShake
  71886. æFc Serial.h
  71887. æT Function
  71888. æD pascal OSErr SerHShake(short refNum,const SerShk *flags); 
  71889. æDT OSErr myVariable = SerHShake((short) refNum,(const SerShk *) flags);
  71890. æMM
  71891. æRT 56
  71892. æRI II-251, N56-1
  71893. æC 
  71894. [Not in ROM]
  71895.  
  71896. Assembly-language note:  SerHShake is equivalent to a Control call with
  71897.                          csCode=10 and csParam through csParam+6 flags.
  71898.  
  71899. SerHShake sets handshake options and other control information, as specified by the
  71900. flags parameter, for the input or output driver having the reference number refNum.
  71901. The flags parameter has the following data structure:
  71902.  
  71903. TYPE SerShk =  PACKED RECORD
  71904.                  fXOn:  Byte;  {XOn/XOff output flow control flag}
  71905.                  fCTS:  Byte;  {CTS hardware handshake flag}
  71906.                  xOn:   CHAR;  {XOn character}
  71907.                  xOff:  CHAR;  {XOff character}
  71908.                  errs:  Byte;  {errors that cause abort}
  71909.                  evts:  Byte;  {status changes that cause events}
  71910.                  fInX:  Byte;  {XOn/XOff input flow control flag}
  71911.                  null:  Byte   {not used}
  71912.                END;
  71913.  
  71914. If fXOn is nonzero, XOn/XOff output flow control is enabled; if fInX is nonzero,
  71915. XOn/XOff input flow control is enabled. XOn and xOff specify the XOn character and
  71916. XOff character used for XOn/XOff flow control. If fCTS is nonzero, CTS hardware
  71917. handshake is enabled. The errs field indicates which errors will cause input requests
  71918. to be aborted; for each type of error, there’s a predefined constant in which the
  71919. corresponding bit is set:
  71920.  
  71921. CONST  parityErr    = 16;    {set if parity error}
  71922.        hwOverrunErr = 32;    {set if hardware overrun error}
  71923.        framingErr   = 64;    {set if framing error}
  71924.  
  71925. Note:  The ROM Serial Driver doesn’t support XOn/XOff input flow control or
  71926.        aborts caused by error conditions.
  71927.  
  71928. The evts field indicates whether changes in the CTS or break status will cause the
  71929. Serial Driver to post device driver events. You can use the following predefined
  71930. constants to set or test the value of evts:
  71931.  
  71932. CONST    ctsEvent   = 32;    {set if CTS change will cause event to be posted}
  71933.          breakEvent = 128;   {set if break status change will cause event }
  71934.                              { to be posted}
  71935.  
  71936. Warning:  Use of this option is discouraged because of the long time that
  71937.           interrupts are disabled while such an event is posted.
  71938.  
  71939. Result codes    noErr    No error
  71940.  
  71941. •••Refer to Technical Note #56:•••
  71942.  
  71943. æKY SerSetBrk
  71944. æFc Serial.h
  71945. æT Function
  71946. æD pascal OSErr SerSetBrk(short refNum); 
  71947. æDT OSErr myVariable = SerSetBrk((short) refNum);
  71948. æMM
  71949. æRI II-252
  71950. æC 
  71951. [Not in ROM]
  71952.  
  71953. Assembly-language note:  SerSetBrk is equivalent to a Control call with
  71954.                          csCode=12.
  71955.  
  71956. SerSetBrk sets break mode in the input or output driver having the reference number
  71957. refNum.
  71958.  
  71959. Result codes    noErr    No error
  71960.  
  71961. æKY SerClrBrk
  71962. æFc Serial.h
  71963. æT Function
  71964. æD pascal OSErr SerClrBrk(short refNum); 
  71965. æDT OSErr myVariable = SerClrBrk((short) refNum);
  71966. æMM
  71967. æRI II-253
  71968. æC 
  71969. [Not in ROM]
  71970.  
  71971. Assembly-language note:  SerClrBrk is equivalent to a Control call with
  71972.                          csCode=11.
  71973.  
  71974. SerClrBrk clears break mode in the input or output driver having the reference number
  71975. refNum.
  71976.  
  71977. Result codes    noErr    No error
  71978.  
  71979. æKY SerGetBuf
  71980. æFc Serial.h
  71981. æT Function
  71982. æD pascal OSErr SerGetBuf(short refNum,long *count); 
  71983. æDT OSErr myVariable = SerGetBuf((short) refNum,(long *) count);
  71984. æRI II-253
  71985. æC 
  71986. [Not in ROM]
  71987.  
  71988. Assembly-language note:  SerGetBuf is equivalent to a Status call with
  71989.                          csCode=2; count is returned in csParam as a long word.
  71990.  
  71991. SerGetBuf returns, in the count parameter, the number of bytes in the buffer of the
  71992. input driver having the reference number refNum.
  71993.  
  71994. Result codes    noErr    No error
  71995.  
  71996. æKY SerStatus
  71997. æFc Serial.h
  71998. æT Function
  71999. æD pascal OSErr SerStatus(short refNum,SerStaRec *serSta); 
  72000. æDT OSErr myVariable = SerStatus((short) refNum,(SerStaRec *) serSta);
  72001. æMM
  72002. æRT 56
  72003. æRI II-253, N56-1
  72004. æC 
  72005. [Not in ROM]
  72006.  
  72007. Assembly-language note:  SerStatus is equivalent to a Status call with
  72008.                          csCode=8; serSta is returned in csParam through
  72009.                          csParam+5.
  72010.  
  72011. SerStatus returns in serSta three words of status information for the input or output
  72012. driver having the reference number refNum. SerSta has the following data structure:
  72013.  
  72014. TYPE  SerStaRec = PACKED RECORD
  72015.                     cumErrs:   Byte;    {cumulative errors}
  72016.                     xOffSent:  Byte;    {XOff sent as input flow control}
  72017.                     rdPend:    Byte;    {read pending flag}
  72018.                     wrPend:    Byte;    {write pending flag}
  72019.                     ctsHold:   Byte;    {CTS flow control hold flag}
  72020.                     xOffHold:  Byte     {XOff flow control hold flag}
  72021.                   END;
  72022.  
  72023. CumErrs indicates which errors have occurred since the last time SerStatus was called:
  72024.  
  72025. CONST  swOverrunErr  = 1;     {set if software overrun error}
  72026.        parityErr     = 16;    {set if parity error}
  72027.        hwOverrunErr  = 32;    {set if hardware overrun error}
  72028.        framingErr    = 64;    {set if framing error}
  72029.  
  72030. If the driver has sent an XOff character, xOffSent will be equal to the following
  72031. predefined constant:
  72032.  
  72033. CONST xOffWasSent = $80; {XOff character was sent}
  72034.  
  72035. If the driver has a Read or Write call pending, rdPend or wrPend, respectively, will
  72036. be nonzero. If output has been suspended because the hardware handshake was disabled,
  72037. ctsHold will be nonzero. If output has been suspended because an XOff character was
  72038. received, xOffHold will be nonzero.
  72039.  
  72040. Result codes    noErr    No error
  72041.  
  72042.  
  72043. æKY setjmp.h
  72044. æC 
  72045. setjmp    longjmp    
  72046.  
  72047.                             Synopsis
  72048.  
  72049. #include <SetJmp.h>
  72050. typedef int jmp_buf[12];
  72051.  
  72052. int setjmp (jmp_buf env);    /* macro only */
  72053. void longjmp (jmp_buf env, int val);
  72054.  
  72055.                            Description
  72056.  
  72057. These functions let you escape from an error or interrupt 
  72058. encountered in a low-level subroutine of your program.
  72059. The setjmp; function saves its stack environment in env for 
  72060. use by longjmp calls that occur later in the same calling chain. 
  72061. (See the examples). The setjmp function returns the value 0.
  72062. When the longjmp ;function is called with the same env, it 
  72063. restores the env saved by the most recent setjmp call with the 
  72064. same env, and the program executes the code at the setjmp 
  72065. location. The program continues as if the preceding call to 
  72066. setjmp had returned the value val.
  72067. The longjmp function cannot cause setjmp to return the value 0. 
  72068. If longjmp is invoked with value val equal to 0, setjmp returns 1. 
  72069. Data values will be those in effect at the time longjmp was 
  72070. called, except for register variables. (See “Warning.”)
  72071.  
  72072. Examples
  72073. Here are two ways to do the same thing. The first method 
  72074. presents setjmp error handling first, then shows the other 
  72075. routines:
  72076.  
  72077. if (setjmp(&env) != 0) { /* env is a global variable */ 
  72078.  /* error handling code executed for the else clause*/
  72079. } else {
  72080.  call (something);
  72081.  /* some call chain that includes a longjmp */
  72082. }    /* end if */
  72083. The second method presents the call chain first, then shows 
  72084. the error handling:
  72085.  
  72086. if (setjmp(&env) == 0){ /* env is a global variable */
  72087.  /* some call chain that includes a longjmp */
  72088.  call (something);
  72089. } else {
  72090.  /* error handling code executed after "return" from longjmp */
  72091. }    /* end if */
  72092.  
  72093. You must call longjmp later than setjmp in the call chain to 
  72094. produce the desired behavior, which is to get setjmp to return a 
  72095. value other than 0. If you exit from the outer routine, where 
  72096. the call to setjmp occurred, then the call to longjmp won’t 
  72097. work properly. 
  72098.  
  72099.                            Warning
  72100.  
  72101. If longjmp is called without a previous call to setjmp with the 
  72102. same env, or if the function that contained the call to setjmp 
  72103. returned before the call to longjmp occurred, results are 
  72104. unpredictable. (See the examples.) 
  72105. After a longjmp, variables that happen to be assigned to 
  72106. registers are restored to the values they had before the call to 
  72107. setjmp, instead of those they had at the time longjmp was called. 
  72108. To avoid this problem, declare “important” variables as 
  72109. volatile, to prohibit their use as register variables.
  72110.  
  72111. See also
  72112. abort, signal
  72113.  
  72114. æKY longjmp
  72115. setjmp
  72116. æFc SetJmp.h
  72117. æC                           Synopsis
  72118.  
  72119. #include <SetJmp.h>
  72120. typedef int jmp_buf[12];
  72121.  
  72122. int setjmp (jmp_buf env);    /* macro only */
  72123. void longjmp (jmp_buf env, int val);
  72124.  
  72125.                            Description
  72126.  
  72127. These functions let you escape from an error or interrupt 
  72128. encountered in a low-level subroutine of your program.
  72129. The setjmp; function saves its stack environment in env for 
  72130. use by longjmp calls that occur later in the same calling chain. 
  72131. (See the examples). The setjmp function returns the value 0.
  72132. When the longjmp ;function is called with the same env, it 
  72133. restores the env saved by the most recent setjmp call with the 
  72134. same env, and the program executes the code at the setjmp 
  72135. location. The program continues as if the preceding call to 
  72136. setjmp had returned the value val.
  72137. The longjmp function cannot cause setjmp to return the value 0. 
  72138. If longjmp is invoked with value val equal to 0, setjmp returns 1. 
  72139. Data values will be those in effect at the time longjmp was 
  72140. called, except for register variables. (See “Warning.”)
  72141.  
  72142. Examples
  72143. Here are two ways to do the same thing. The first method 
  72144. presents setjmp error handling first, then shows the other 
  72145. routines:
  72146.  
  72147. if (setjmp(&env) != 0) { /* env is a global variable */ 
  72148.  /* error handling code executed for the else clause*/
  72149. } else {
  72150.  call (something);
  72151.  /* some call chain that includes a longjmp */
  72152. }    /* end if */
  72153. The second method presents the call chain first, then shows 
  72154. the error handling:
  72155.  
  72156. if (setjmp(&env) == 0){ /* env is a global variable */
  72157.  /* some call chain that includes a longjmp */
  72158.  call (something);
  72159. } else {
  72160.  /* error handling code executed after "return" from longjmp */
  72161. }    /* end if */
  72162.  
  72163. You must call longjmp later than setjmp in the call chain to 
  72164. produce the desired behavior, which is to get setjmp to return a 
  72165. value other than 0. If you exit from the outer routine, where 
  72166. the call to setjmp occurred, then the call to longjmp won’t 
  72167. work properly. 
  72168.  
  72169.                            Warning
  72170.  
  72171. If longjmp is called without a previous call to setjmp with the 
  72172. same env, or if the function that contained the call to setjmp 
  72173. returned before the call to longjmp occurred, results are 
  72174. unpredictable. (See the examples.) 
  72175. After a longjmp, variables that happen to be assigned to 
  72176. registers are restored to the values they had before the call to 
  72177. setjmp, instead of those they had at the time longjmp was called. 
  72178. To avoid this problem, declare “important” variables as 
  72179. volatile, to prohibit their use as register variables.
  72180.  
  72181. See also
  72182. abort, signal
  72183.  
  72184. æKY longjmpæ
  72185. æDT 
  72186. void myVariable = longjmp ((jmp_buf) env, (int) val);
  72187.  
  72188. æKY setjmpæ
  72189. æDT 
  72190. int myVariable = int setjmp ((jmp_buf) env);  
  72191.  
  72192. æKY ShutDown.h
  72193. æKL ShutDwnInstall
  72194. ShutDwnPower
  72195. ShutDwnRemove
  72196. ShutDwnStart
  72197.  
  72198. sdOnDrivers
  72199. sdOnPowerOff
  72200. sdOnRestart
  72201. sdOnUnmount
  72202. sdRestartOrPower
  72203. ShutdwnProcPtr
  72204.  
  72205. æKY sdOnPowerOff
  72206. æFc ShutDown.h
  72207. æT #define
  72208. æD #define sdOnPowerOff 1 /*call procedure before power off.*/
  72209. æC 
  72210.  
  72211. æKY sdOnRestart
  72212. æFc ShutDown.h
  72213. æT #define
  72214. æD #define sdOnRestart 2 /*call procedure before restart.*/
  72215. æC 
  72216.  
  72217. æKY sdOnUnmount
  72218. æFc ShutDown.h
  72219. æT #define
  72220. æD #define sdOnUnmount 4 /*call procedure before unmounting.*/
  72221. æC 
  72222.  
  72223. æKY sdOnDrivers
  72224. æFc ShutDown.h
  72225. æT #define
  72226. æD #define sdOnDrivers 8 /*call procedure before closing drivers.*/
  72227. æC 
  72228.  
  72229. æKY sdRestartOrPower
  72230. æFc ShutDown.h
  72231. æT #define
  72232. æD #define sdRestartOrPower 3 /*call before either power off or restart.*/
  72233. æC 
  72234.  
  72235. æKY ShutdwnProcPtr
  72236. æFc ShutDown.h
  72237. æT typedef
  72238. æD typedef pascal void (*ShutDwnProcPtr)(void);
  72239. æC 
  72240.  
  72241. æKY ShutDwnPower
  72242. æFc ShutDown.h
  72243. æT Function
  72244. æTN A895
  72245. æD pascal void ShutDwnPower(void)
  72246.     = {0x3F3C,0x0001,0xA895}; 
  72247. æDT ShutDwnPower()(void);
  72248. æRI V-587
  72249. æC 
  72250. ShutDwnPower performs system housekeeping, executes any shutdown procedures you may
  72251. have installed with ShutDwnInstall, and turns the machine off.  (If the machine must
  72252. be turned off manually, the shutdown alert is presented.)
  72253.  
  72254. Assembly-language note:  You can invoke each of the Shutdown Manager routines
  72255.                          with a macro that has the same name as the routine
  72256.                          preceded by an underscore.  These macros expand to
  72257.                          invoke the _Shutdown trap macro.  The _Shutdown trap
  72258.                          determines which routine to execute from a routine
  72259.                          selector, an integer that’s passed to it in a word on
  72260.                          the stack.  The routine selectors are as follows:
  72261.  
  72262.                            sdPowerOff    .EQU    1
  72263.                            sdRestart     .EQU    2
  72264.                            sdInstall     .EQU    3
  72265.                            sdRemove      .EQU    4
  72266.  
  72267. æKY ShutDwnStart
  72268. æFc ShutDown.h
  72269. æT Function
  72270. æTN A895
  72271. æD pascal void ShutDwnStart(void)
  72272.     = {0x3F3C,0x0002,0xA895}; 
  72273. æDT ShutDwnStart()(void);
  72274. æRI V-587
  72275. æC 
  72276. ShutDwnPower performs system housekeeping, executes any shutdown procedures you may
  72277. have installed with ShutDwnInstall, and reboots the machine.
  72278.  
  72279. Assembly-language note:  ShutDwnStart results in the execution of the Reset
  72280.                          instruction, followed by a jump to the ROM boot code
  72281.                          (the address is the value of the global variable
  72282.                          ROMBase + 10).
  72283.  
  72284. æKY ShutDwnInstall
  72285. æFc ShutDown.h
  72286. æT Function
  72287. æTN A895
  72288. æD pascal void ShutDwnInstall(ShutdwnProcPtr shutDownProc,short flags)
  72289.     = {0x3F3C,0x0003,0xA895}; 
  72290. æDT ShutDwnInstall((ShutdwnProcPtr) shutDownProc,(short) flags);
  72291. æMM
  72292. æRI V-588
  72293. æC 
  72294. ShutDwnInstall installs the shutdown procedure pointed to by shutDwnProc.  The flags
  72295. parameter indicates where in the shutdown process to execute your shutdown procedure.
  72296.  The following masks are provided for setting the bits of the flags parameter:
  72297.  
  72298. CONST  sdOnPowerOff     = 1;     {call procedure before power off}
  72299.        sdOnRestart      = 2;     {call procedure before restart}
  72300.        sdOnUnmount     = 4;      {call procedure before unmounting}
  72301.        sdOnDrivers       = 8;    {call procedure before closing drivers}
  72302.        sdRestartOrPower = sdOnPowerOff + sdOnRestart  {call procedure before }
  72303.                                                 { either power off or restart}
  72304.  
  72305. Assembly-language note:  You can invoke each of the Shutdown Manager routines
  72306.                          with a macro that has the same name as the routine
  72307.                          preceded by an underscore.  These macros expand to
  72308.                          invoke the _Shutdown trap macro.  The _Shutdown trap
  72309.                          determines which routine to execute from a routine
  72310.                          selector, an integer that’s passed to it in a word on
  72311.                          the stack.  The routine selectors are as follows:
  72312.  
  72313.                            sdPowerOff    .EQU    1
  72314.                            sdRestart     .EQU    2
  72315.                            sdInstall     .EQU    3
  72316.                            sdRemove      .EQU    4
  72317.  
  72318. æKY ShutDwnRemove
  72319. æFc ShutDown.h
  72320. æT Function
  72321. æTN A895
  72322. æD pascal void ShutDwnRemove(ShutdwnProcPtr shutDownProc)
  72323.     = {0x3F3C,0x0004,0xA895}; 
  72324. æDT ShutDwnRemove((ShutdwnProcPtr) shutDownProc);
  72325. æMM
  72326. æRI V-588
  72327. æC 
  72328. ShutDwnRemove removes the shutdown procedure pointed to by shutDwnProc.
  72329.  
  72330. Note:  If the procedure was marked for execution at a number of points in the
  72331.        shutdown process (say, for instance, at unmounting, restart, and power
  72332.        off), it will be removed at all points.
  72333.  
  72334. Assembly-language note:  You can invoke each of the Shutdown Manager routines
  72335.                          with a macro that has the same name as the routine
  72336.                          preceded by an underscore.  These macros expand to
  72337.                          invoke the _Shutdown trap macro.  The _Shutdown trap
  72338.                          determines which routine to execute from a routine
  72339.                          selector, an integer that’s passed to it in a word on
  72340.                          the stack.  The routine selectors are as follows:
  72341.  
  72342.                            sdPowerOff    .EQU    1
  72343.                            sdRestart     .EQU    2
  72344.                            sdInstall     .EQU    3
  72345.                            sdRemove      .EQU    4
  72346.  
  72347.  
  72348. æKY Signal.h
  72349. æKL IEraise
  72350. IEsignal
  72351.  
  72352. SIGABRT
  72353. SIGFPE
  72354. SIGILL
  72355. SIGINT
  72356. SIGSEGV
  72357. SIGTERM
  72358. SIG_DFL
  72359. SIG_ERR
  72360. SIG_HOLD
  72361. SIG_IGN
  72362. SIG_RELEASE
  72363.  
  72364. æKY SIG_ERR
  72365. æFc Signal.h
  72366. æT #define
  72367. æD #define SIG_ERR -1 /* Returned by IESignal on error */
  72368. æC 
  72369.  
  72370. æKY SIG_IGN
  72371. æFc Signal.h
  72372. æT #define
  72373. æD #define SIG_IGN 0
  72374. æC 
  72375.  
  72376. æKY SIG_DFL
  72377. æFc Signal.h
  72378. æT #define
  72379. æD #define SIG_DFL 1
  72380. æC 
  72381.  
  72382. æKY SIG_HOLD
  72383. æFc Signal.h
  72384. æT #define
  72385. æD #define SIG_HOLD 3
  72386. æC 
  72387.  
  72388. æKY SIG_RELEASE
  72389. æFc Signal.h
  72390. æT #define
  72391. æD #define SIG_RELEASE 5
  72392. æC 
  72393.  
  72394. æKY SIGABRT
  72395. æFc Signal.h
  72396. æT #define
  72397. æD #define SIGABRT 0x0001
  72398. æC 
  72399.  
  72400. æKY SIGINT
  72401. æFc Signal.h
  72402. æT #define
  72403. æD #define SIGINT 0x0002 /* Currently only SIGINT implemented */
  72404. æC 
  72405.  
  72406. æKY SIGFPE
  72407. æFc Signal.h
  72408. æT #define
  72409. æD #define SIGFPE 0x0004
  72410. æC 
  72411.  
  72412. æKY SIGILL
  72413. æFc Signal.h
  72414. æT #define
  72415. æD #define SIGILL 0x0008
  72416. æC 
  72417.  
  72418. æKY SIGSEGV
  72419. æFc Signal.h
  72420. æT #define
  72421. æD #define SIGSEGV 0x0010
  72422. æC 
  72423.  
  72424. æKY SIGTERM
  72425. æFc Signal.h
  72426. æT #define
  72427. æD #define SIGTERM 0x0020
  72428. æC 
  72429.  
  72430. æKY IEraise
  72431. æFc Signal.h
  72432. æT Function
  72433. æD long IEraise(long sigNum); 
  72434. æDT long myVariable = IEraise((long) sigNum);
  72435. æC 
  72436.  
  72437. æKY IEsignal
  72438. æFc Signal.h
  72439. æT Function
  72440. æD long IEsignal(long sigNum,SignalHandler sigHdlr); 
  72441. æDT long myVariable = IEsignal((long) sigNum,(SignalHandler) sigHdlr);
  72442. æC 
  72443.  
  72444.  
  72445. æKY Slots.h
  72446. æKL InitSDeclMgr
  72447. InsertSRTRec
  72448. OpenSlot
  72449. SCalcSPointer
  72450. SCalcStep
  72451. SCardChanged
  72452. SCkCardStat
  72453. SDeleteSRTRec
  72454. SetSRsrcState
  72455. SExec
  72456. SFindBigDevBase
  72457. SFindDevBase
  72458. SFindSInfoRecPtr
  72459. SFindSRsrcPtr
  72460. SFindStruct
  72461. SGetBlock
  72462. SGetCString
  72463. SGetDriver
  72464. SGetSRsrc
  72465. SGetSRsrcPtr
  72466. SGetTypeSRsrc
  72467. SInitPRAMRecs
  72468. SInitSRsrcTable
  72469. SIntInstall
  72470. SIntRemove
  72471. SNextSRsrc
  72472. SNextTypeSRsrc
  72473. SOffsetData
  72474. SPrimaryInit
  72475. SPtrToSlot
  72476. SPutPRAMRec
  72477. SReadByte
  72478. SReadDrvrName
  72479. SReadFHeader
  72480. SReadInfo
  72481. SReadLong
  72482. SReadPBSize
  72483. SReadPRAMRec
  72484. SReadStruct
  72485. SReadWord
  72486. SRsrcInfo
  72487. SSearchSRT
  72488. SUpdateSRT
  72489. SVersion
  72490.  
  72491. fall
  72492. fCardIsChanged
  72493. fCkForNext
  72494. fCkForSame
  72495. FHeaderRec
  72496. FHeaderRecPtr
  72497. fnext
  72498. foneslot
  72499. fWarmStart
  72500. SDMRecord
  72501. SEBlock
  72502. SInfoRecord
  72503. SInfoRecPtr
  72504. SlotIntQElement
  72505. SpBlock
  72506. SpBlockPtr
  72507. SQElemPtr
  72508. stateNil
  72509. statePInit
  72510. statePRAMInit
  72511. stateSDMInit
  72512. stateSInit
  72513.  
  72514. æKY fCardIsChanged
  72515. æFc Slots.h
  72516. æT #define
  72517. æD #define fCardIsChanged 1 /*Card is Changed field in StatusFlags field of sInfoArray*/
  72518. æC 
  72519.  
  72520. æKY fCkForSame
  72521. æFc Slots.h
  72522. æT #define
  72523. æD #define fCkForSame 0 /*For SearchSRT. Flag to check for SAME sResource in the table. */
  72524. æC 
  72525.  
  72526. æKY fCkForNext
  72527. æFc Slots.h
  72528. æT #define
  72529. æD #define fCkForNext 1 /*For SearchSRT. Flag to check for NEXT sResource in the table. */
  72530. æC 
  72531.  
  72532. æKY fWarmStart
  72533. æFc Slots.h
  72534. æT #define
  72535. æD #define fWarmStart 2 /*If this bit is set then warm start else cold start.*/
  72536. æC 
  72537.  
  72538. æKY stateNil
  72539. æFc Slots.h
  72540. æT #define
  72541. æD #define stateNil 0 /*State*/
  72542. æC 
  72543.  
  72544. æKY stateSDMInit
  72545. æFc Slots.h
  72546. æT #define
  72547. æD #define stateSDMInit 1 /*:Slot declaration manager Init*/
  72548. æC 
  72549.  
  72550. æKY statePRAMInit
  72551. æFc Slots.h
  72552. æT #define
  72553. æD #define statePRAMInit 2 /*:sPRAM record init*/
  72554. æC 
  72555.  
  72556. æKY statePInit
  72557. æFc Slots.h
  72558. æT #define
  72559. æD #define statePInit 3 /*:Primary init*/
  72560. æC 
  72561.  
  72562. æKY stateSInit
  72563. æFc Slots.h
  72564. æT #define
  72565. æD #define stateSInit 4 /*:Secondary init*/
  72566. æC 
  72567.  
  72568. æKY fall
  72569. æFc Slots.h
  72570. æT #define
  72571. æD 
  72572. /*  flags for spParamData  */
  72573.  
  72574. #define fall 0 /* bit 0: set=search enabled/disabled sRsrc's */
  72575. æC 
  72576.  
  72577. æKY foneslot
  72578. æFc Slots.h
  72579. æT #define
  72580. æD #define foneslot 1 /*       1: set=search sRsrc's in given slot only */
  72581. æC 
  72582.  
  72583. æKY fnext
  72584. æFc Slots.h
  72585. æT #define
  72586. æD #define fnext 2 /*       2: set=search for next sRsrc */
  72587. æC 
  72588.  
  72589. æKY SlotIntQElement
  72590. SQElemPtr
  72591. æFc Slots.h
  72592. æT struct
  72593. æD struct SlotIntQElement {
  72594.     Ptr sqLink; /*ptr to next element*/
  72595.     short sqType; /*queue type ID for validity*/
  72596.     short sqPrio; /*priority*/
  72597.     ProcPtr sqAddr; /*interrupt service routine*/
  72598.     long sqParm; /*optional A1 parameter*/
  72599. };
  72600.  
  72601. typedef struct SlotIntQElement SlotIntQElement;
  72602. typedef SlotIntQElement *SQElemPtr;
  72603.  
  72604. æC 
  72605.  
  72606. æKY SpBlock
  72607. SpBlockPtr
  72608. æFc Slots.h
  72609. æT struct
  72610. æD struct SpBlock {
  72611.     long spResult; /*FUNCTION Result*/
  72612.     Ptr spsPointer; /*structure pointer*/
  72613.     long spSize; /*size of structure*/
  72614.     long spOffsetData; /*offset/data field used by sOffsetData*/
  72615.     Ptr spIOFileName; /*ptr to IOFile name for sDisDrvrName*/
  72616.     Ptr spsExecPBlk; /*pointer to sExec parameter block.*/
  72617.     Ptr spParamData; /*misc parameter data (formerly spStackPtr).*/
  72618.     long spMisc; /*misc field for SDM.*/
  72619.     long spReserved; /*reserved for future expansion*/
  72620.     short spIOReserved; /*Reserved field of Slot Resource Table*/
  72621.     short spRefNum; /*RefNum*/
  72622.     short spCategory; /*sType: Category*/
  72623.     short spCType; /*Type*/
  72624.     short spDrvrSW; /*DrvrSW*/
  72625.     short spDrvrHW; /*DrvrHW*/
  72626.     char spTBMask; /*type bit mask bits 0..3 mask words 0..3*/
  72627.     char spSlot; /*slot number*/
  72628.     char spID; /*structure ID*/
  72629.     char spExtDev; /*ID of the external device*/
  72630.     char spHwDev; /*Id of the hardware device.*/
  72631.     char spByteLanes; /*bytelanes from card ROM format block*/
  72632.     char spFlags; /*standard flags*/
  72633.     char spKey; /*Internal use only*/
  72634. };
  72635.  
  72636. typedef struct SpBlock SpBlock;
  72637. typedef SpBlock *SpBlockPtr;
  72638.  
  72639. æC 
  72640. »Slot Parameter Block
  72641.  
  72642. Data transfer between the Slot Manager and card firmware takes place through the Slot
  72643. Parameter Block, which has this structure:
  72644.  
  72645. TYPE
  72646.   SpBlockPtr = ^SpBlock;
  72647.   SpBlock    = PACKED RECORD
  72648.                  spResult:     LONGINT;     {FUNCTION result used by }
  72649.                                             { every function}
  72650.                  spsPointer:   Ptr;         {structure pointer}
  72651.                  spSize:       LONGINT;     {size of structure}
  72652.                  spOffsetData: LONGINT;     {offset/data field used by }
  72653.                                             { sOffsetData}
  72654.                  spIOFileName: Ptr;         {pointer to IOFile name used }
  72655.                                             { by sDisDrvrName}
  72656.                  spsExecPBlk:  Ptr;         {pointer to sExec parameter block}
  72657.                  spStackPtr:   Ptr;         {old Stack pointer}
  72658.                  spMisc:       LONGINT;     {misc field for SDM}
  72659.                  spReserved:   LONGINT;     {reserved for future }
  72660.                                             { expansion}
  72661.                  spIOReserved: INTEGER;     {reserved field of Slot }
  72662.                                             { Resource Table}
  72663.                  spRefNum:     INTEGER;     {RefNum}
  72664.                  spCategory:   INTEGER;     {sType:Category}
  72665.                  spCType:      INTEGER;     {sType:Type}
  72666.                  spDrvrSW:     INTEGER;     {sType:DrvrSW}
  72667.                  spDrvrHW:     INTEGER;     {sType:DrvrHW}
  72668.                  spTBMask:     SignedByte;  {type bit mask (Bits 0..3 }
  72669.                                             { mask words 0..3}
  72670.                  spSlot:       SignedByte;  {slot number}
  72671.                  spID:         SignedByte;  {structure ID}
  72672.                  spExtDev:     SignedByte;  {ID of the external device}
  72673.                  spHWDev:      SignedByte;  {ID of the hardware device}
  72674.                  spByteLanes:  SignedByte;  {ByteLanes from format block }
  72675.                                             { in card ROM}
  72676.                  spFlags:      SignedByte;  {standard flags}
  72677.                  spKey:        SignedByte;  {internal use only}
  72678.                END;
  72679.  
  72680. Assembly-language note:  The Slot Parameter Block has the following structure
  72681.                          in assembly language:
  72682.  
  72683.                            spResult      Function result (long)
  72684.                            spsPointer    Structure pointer (long)
  72685.                            spOffsetData  Offset/Data field (long)
  72686.                            spIOFileName  Pointer to IOFileName (long)
  72687.                            spsExecBlk    Pointer to sExec parameter block (long)
  72688.                            spStackPtr    Old stack pointer (long)
  72689.                            spMisc        Reserved for Slot Manager (long)
  72690.                            spReserved    Reserved (long)
  72691.                            spIOReserved  Reserved field of Slot Resource
  72692.                                          Table (word)
  72693.                            spRefNum      Slot Resource Table reference
  72694.                                          number (word)
  72695.                            spCategory    sResource type: Category (word)
  72696.                            spType        sResource type: Type (word)
  72697.                            spDrvrSW      sResource type: Driver software
  72698.                                          identifier (word)
  72699.                            spDrvrHW      sResource type: Driver hardware
  72700.                                          identifier (word)
  72701.                            spTBMask      Type bit mask (byte)
  72702.                            spSlot        Slot number (byte)
  72703.                            spId          sResource list ID (byte)
  72704.                            spExtDev      External device identifier (byte)
  72705.                            spHWDev       Hardware device identifier (byte)
  72706.                            spByteLanes   ByteLanes value from format block
  72707.                                          in card firmware (byte)
  72708.                            spFlags       Standard flags (byte)
  72709.                            spKey         Reserved (byte)
  72710.                            spBlockSize   Size of Slot Parameter Block
  72711.  
  72712. æKY SInfoRecord
  72713. SInfoRecPtr
  72714. æFc Slots.h
  72715. æT struct
  72716. æD struct SInfoRecord {
  72717.     Ptr siDirPtr; /*Pointer to directory*/
  72718.     short siInitStatusA; /*initialization E*/
  72719.     short siInitStatusV; /*status returned by vendor init code*/
  72720.     char siState; /*initialization state*/
  72721.     char siCPUByteLanes; /*0=[d0..d7] 1=[d8..d15]*/
  72722.     char siTopOfROM; /*Top of ROM= $FssFFFFx: x is TopOfROM*/
  72723.     char siStatusFlags; /*bit 0 - card is changed*/
  72724.     short siTOConst; /*Time Out C for BusErr*/
  72725.     char siReserved[2]; /*reserved*/
  72726.     Ptr siROMAddr; /* addr of top of ROM */
  72727.     char siSlot; /* slot number */
  72728.     char siPadding[3]; /* reserved */
  72729. };
  72730.  
  72731. typedef struct SInfoRecord SInfoRecord;
  72732. typedef SInfoRecord *SInfoRecPtr;
  72733.  
  72734. æC 
  72735.  
  72736. æKY SDMRecord
  72737. æFc Slots.h
  72738. æT struct
  72739. æD struct SDMRecord {
  72740.     ProcPtr sdBEVSave; /*Save old BusErr vector*/
  72741.     ProcPtr sdBusErrProc; /*Go here to determine if it is a BusErr*/
  72742.     ProcPtr sdErrorEntry; /*Go here if BusErrProc finds real BusErr*/
  72743.     long sdReserved; /*Reserved*/
  72744. };
  72745.  
  72746. typedef struct SDMRecord SDMRecord;
  72747. æC 
  72748.  
  72749. æKY FHeaderRec
  72750. FHeaderRecPtr
  72751. æFc Slots.h
  72752. æT struct
  72753. æD struct FHeaderRec {
  72754.     long fhDirOffset; /*offset to directory*/
  72755.     long fhLength; /*length of ROM*/
  72756.     long fhCRC; /*CRC*/
  72757.     char fhROMRev; /*revision of ROM*/
  72758.     char fhFormat; /*format - 2*/
  72759.     long fhTstPat; /*test pattern*/
  72760.     char fhReserved; /*reserved*/
  72761.     char fhByteLanes; /*ByteLanes*/
  72762. };
  72763.  
  72764. typedef struct FHeaderRec FHeaderRec;
  72765. typedef FHeaderRec *FHeaderRecPtr;
  72766.  
  72767. æC 
  72768.  
  72769. æKY SEBlock
  72770. æFc Slots.h
  72771. æT struct
  72772. æD struct SEBlock {
  72773.     unsigned char seSlot; /*Slot number.*/
  72774.     unsigned char sesRsrcId; /*sResource Id.*/
  72775.     short seStatus; /*Status of code executed by sExec.*/
  72776.     unsigned char seFlags; /*Flags*/
  72777.     unsigned char seFiller0; /*Filler, must be SignedByte to align on odd boundry*/
  72778.     unsigned char seFiller1; /*Filler*/
  72779.     unsigned char seFiller2; /*Filler*/
  72780.     long seResult; /*Result of sLoad.*/
  72781.     long seIOFileName; /*Pointer to IOFile name.*/
  72782.     unsigned char seDevice; /*Which device to read from.*/
  72783.     unsigned char sePartition; /*The partition.*/
  72784.     unsigned char seOSType; /*Type of OS.*/
  72785.     unsigned char seReserved; /*Reserved field.*/
  72786.     unsigned char seRefNum; /*RefNum of the driver.*/
  72787.     unsigned char seNumDevices; /* Number of devices to load.*/
  72788.     unsigned char seBootState; /*State of StartBoot code.*/
  72789. };
  72790.  
  72791. typedef struct SEBlock SEBlock;
  72792. æC 
  72793. »SExec Block
  72794.  
  72795. For the routine sExec, data transfer between the Slot Manager and card firmware also
  72796. takes place through the SExec Block, which has this structure:
  72797.  
  72798.   SEBlockPtr = ^SEBlock;
  72799.   SEBlock    = PACKED RECORD
  72800.                  seSlot:        SignedByte;  {slot number}
  72801.                  sesRsrcId:     SignedByte;  {sResource Id}
  72802.                  seStatus:      INTEGER;     {status of code executed by sExec}
  72803.                  seFlags:       SignedByte;  {flags}
  72804.                  seFiller0:     SignedByte;  {filler--SignedByte to align }
  72805.                                              { on word boundary}
  72806.                  seFiller1:     SignedByte;  {filler}
  72807.                  seFiller2:     SignedByte;  {filler}
  72808.                  seResult:      LONGINT;     {result of sLoad}
  72809.                  seIOFileName:  LONGINT;     {pointer to IOFile name}
  72810.                  seDevice:      SignedByte;  {which device to read from}
  72811.                  sePartition:   SignedByte;  {the partition}
  72812.                  seOSType:      SignedByte;  {type of OS}
  72813.                  seReserved:    SignedByte;  {reserved field}
  72814.                  seRefNum:      SignedByte;  {RefNum of the driver}
  72815.                  seNumDevices:  SignedByte;  {number of devices to load}
  72816.                  seBootState:   SignedByte;  {state of StartBoot code}
  72817.                END;
  72818.  
  72819. Assembly-language note:  The SExec Block has the following structure in
  72820.                          assembly language:
  72821.  
  72822.                            seSlot        Slot number (byte)
  72823.                            sesRsrcId     sResource list ID (byte)
  72824.                            seStatus      Status of code executed by sExec (word)
  72825.                            seFlags       Flags (byte)
  72826.                            seFiller0     Filler (byte)
  72827.                            seFiller1     Filler (byte)
  72828.                            seFiller2     Filler (byte)
  72829.                            seResult      Result of sLoad (long)
  72830.                            seIOFileName  Pointer to IOFile name (long)
  72831.                            seDevice      Which device to read from (byte)
  72832.                            sePartition   Device partition (byte)
  72833.                            seOSType      Operating system type (byte)
  72834.                            seReserved    Reserved (byte)
  72835.                            seRefNum      RefNum of the driver (byte)
  72836.                            seNumDevices  Number of devices to load (byte)
  72837.                            seBootState   Status of the StartBoot code (byte)
  72838.  
  72839. The seOSType parameter has these values:
  72840.  
  72841.   Name         Value    Description 
  72842.   
  72843.   sMacOS68000    1      Load routine will run on a Macintosh
  72844.                         computer with MC68000 processor
  72845.   sMacOS68020    2      Load routine will run on a Macintosh
  72846.                         computer with MC68020 processor
  72847.  
  72848. Other values may be used for future Macintosh family operating systems.
  72849.  
  72850. æKY SIntInstall
  72851. æFc Slots.h
  72852. æT Function
  72853. æD pascal OSErr SIntInstall(SQElemPtr sIntQElemPtr,short theSlot); 
  72854. æDT OSErr myVariable = SIntInstall((SQElemPtr) sIntQElemPtr,(short) theSlot);
  72855. æRT 221
  72856. æRI V-427, C9-9
  72857. æC 
  72858. The Device Manager provides two new routines to implement the interrupt queue process
  72859. just described: SIntInstall and SIntRemove. They are described below.
  72860.  
  72861. FUNCTION SIntInstall(sIntQElemPtr: SQElemPtr; theSlot: INTEGER) : OsErr;
  72862.  
  72863. Trap macro  _SIntInstall
  72864. On entry    D0:  slot number (word)
  72865.             A0:  address of slot queue element
  72866. On exit     D0:  error code
  72867.  
  72868. SIntInstall adds a new element (pointed to by sIntQElemPtr) to the interrupt queue
  72869. for the slot whose number is given in theSlot.  As explained in the Slot Manager
  72870. chapter, slots are numbered from 9 to $E.
  72871.  
  72872. Assembly-language note:  From assembly language, this routine has the
  72873.                          following calling sequence (assuming A0 points
  72874.                          to a slot queue element):
  72875.  
  72876.                            LEA          PollRoutine,A1     ;get routine address
  72877.                            MOVE.L       A1,SQAddr(A0)      ;set address
  72878.                            MOVE.W       Prio,SQPrio(A0)    ;set priority
  72879.                            MOVE.L       A1Parm,SQParm(A0)  ;save A1 parameter
  72880.                            MOVE.W       Slot,D0            ;set slot number
  72881.                            _SIntInstall                    ;do installation
  72882.  
  72883.                          This code causes the routine at label PollRoutine to
  72884.                          be called as a result of an interrupt from the
  72885.                          specified slot (9..$E).   The Device Manager will
  72886.                          poll the slot which has the highest priority first if
  72887.                          two or more slots request an interrupt simultaneously.
  72888.  
  72889. æKY SIntRemove
  72890. æFc Slots.h
  72891. æT Function
  72892. æD pascal OSErr SIntRemove(SQElemPtr sIntQElemPtr,short theSlot); 
  72893. æDT OSErr myVariable = SIntRemove((SQElemPtr) sIntQElemPtr,(short) theSlot);
  72894. æRI V-427, C9-9
  72895. æC 
  72896. Trap macro  _SIntRemove
  72897. On entry    D0:  slot number (word)
  72898.             A0:  address of slot queue element
  72899. On exit     D0:  error code
  72900.  
  72901. SIntRemove removes an element (pointed to by sIntQElemPtr) from the interrupt queue
  72902. for the slot whose number is given in theSlot.  As explained in the Slot Manager
  72903. chapter, slots are numbered from 9 to $E.
  72904.  
  72905. Assembly-language note:  From assembly language, this routine has the
  72906.                          following calling sequence (assuming A0 points
  72907.                          to a slot queue element):
  72908.  
  72909.                            LEA         MySQEl,A0    ;pointer to queue element
  72910.                            _SIntRemove              ;remove it
  72911.  
  72912.                          This routine lets you remove an interrupt handler
  72913.                          from the system without causing a crash.
  72914.  
  72915. Your driver polling routine will be called with the following assembly-language
  72916. code:
  72917.  
  72918.   MOVE.L    A1Parm,A1      ;load A1 Parameter
  72919.   JSR       PollRoutine    ;call polling routine
  72920.  
  72921. Your polling routine should preserve the contents of all registers except A1 and D0. 
  72922. It should return to the Device Manager with an RTS instruction. D0 should be set to
  72923. zero to indicate that the polling routine did not service the interrupt, or nonzero
  72924. to indicate the interrupt has been serviced.  The polling routine should not set the
  72925. processor priority below 2, and should return with the processor priority equal to 2.
  72926.  The Device Manager resets the VIA2 int flag and executes an RTE to the interrrupted
  72927. task when a polling routine indicates that the interrupt is satisfied; otherwise, it
  72928. calls the next lower-priority polling routine for that slot.  If none exists, a
  72929. system error results.
  72930.  
  72931. æKY SReadByte
  72932. æFc Slots.h
  72933. æT Function
  72934. æD pascal OSErr SReadByte(SpBlockPtr spBlkPtr); 
  72935. æDT OSErr myVariable = SReadByte((SpBlockPtr) spBlkPtr);
  72936. æRI V-444
  72937. æC 
  72938. Trap macro: _SReadByte
  72939.  
  72940. Required Parameters
  72941.     -->    spsPointer   
  72942.     -->    spId
  72943.     <--    spResult
  72944.  
  72945. Other Parameters Affected
  72946.            spOffsetData
  72947.            spByteLanes
  72948.  
  72949. The trap macro SReadByte returns in spResult an 8-bit value identified by spId from
  72950. the sResource list pointed to by spsPointer. This routine’s low-order byte can return
  72951. nonfatal error reports.
  72952.  
  72953. æKY SReadWord
  72954. æFc Slots.h
  72955. æT Function
  72956. æD pascal OSErr SReadWord(SpBlockPtr spBlkPtr); 
  72957. æDT OSErr myVariable = SReadWord((SpBlockPtr) spBlkPtr);
  72958. æRI V-445
  72959. æC 
  72960. Trap macro: _SReadWord
  72961.  
  72962. Required Parameters
  72963.     -->    spsPointer
  72964.     -->    spId
  72965.     <--    spResult
  72966.  
  72967. Other Parameters Affected
  72968.            spOffsetData
  72969.            spByteLanes
  72970.  
  72971. The trap macro SReadWord returns in the low-order word of spResult a 16-bit value
  72972. identified by spId from the sResource list pointed to by spsPointer. This routine can
  72973. return nonfatal error reports.
  72974.  
  72975. æKY SReadLong
  72976. æFc Slots.h
  72977. æT Function
  72978. æD pascal OSErr SReadLong(SpBlockPtr spBlkPtr); 
  72979. æDT OSErr myVariable = SReadLong((SpBlockPtr) spBlkPtr);
  72980. æRI V-445
  72981. æC 
  72982. Trap macro: _SReadLong
  72983.  
  72984. Required Parameters
  72985.     -->    spsPointer
  72986.     -->    spId
  72987.     <--    spResult
  72988.  
  72989. Other Parameters Affected
  72990.            spOffsetData
  72991.            spByteLanes
  72992.            spSize
  72993.  
  72994. The trap macro SReadLong returns in spResult a 32-bit value identified by spId from
  72995. the sResource list pointed to by spsPointer. This routine can return nonfatal error
  72996. reports.
  72997.  
  72998. æKY SGetCString
  72999. æFc Slots.h
  73000. æT Function
  73001. æD pascal OSErr SGetCString(SpBlockPtr spBlkPtr); 
  73002. æDT OSErr myVariable = SGetCString((SpBlockPtr) spBlkPtr);
  73003. æMM
  73004. æRI V-445
  73005. æC 
  73006. Trap macro: _SGetCString
  73007.  
  73008. Required Parameters
  73009.     -->    spsPointer
  73010.     -->    spId
  73011.     <--    spResult
  73012.  
  73013. Other Parameters Affected
  73014.            spOffsetData
  73015.            spByteLanes
  73016.            spSize
  73017.            spFlags
  73018.  
  73019. The trap macro SGetCString copies a cString identified by spId from the sResource
  73020. list pointed to by spsPointer to a buffer pointed to by spResult. Memory for this
  73021. buffer is automatically allocated by SGetCString.
  73022.  
  73023. æKY SGetBlock
  73024. æFc Slots.h
  73025. æT Function
  73026. æD pascal OSErr SGetBlock(SpBlockPtr spBlkPtr); 
  73027. æDT OSErr myVariable = SGetBlock((SpBlockPtr) spBlkPtr);
  73028. æMM
  73029. æRI V-445
  73030. æC 
  73031. Trap macro: _SGetBlock
  73032.  
  73033. Required Parameters
  73034.     -->    spsPointer
  73035.     -->    spId
  73036.     <--    spResult
  73037.  
  73038. Other Parameters Affected
  73039.            spOffsetData
  73040.            spByteLanes
  73041.            spSize
  73042.            spFlags
  73043.  
  73044. The trap macro SGetBlock copies the sBlock from the sResource list pointed to by
  73045. spsPointer and identified by spId into a new block and returns a pointer to it in
  73046. spResult.  The pointer in spResult should be disposed of by using the Memory Manager
  73047. routine DisposPtr.
  73048.  
  73049. æKY SFindStruct
  73050. æFc Slots.h
  73051. æT Function
  73052. æD pascal OSErr SFindStruct(SpBlockPtr spBlkPtr); 
  73053. æDT OSErr myVariable = SFindStruct((SpBlockPtr) spBlkPtr);
  73054. æRI V-446
  73055. æC 
  73056. Trap macro: _ sFindStruct
  73057.  
  73058. Required Parameters
  73059.     -->    spId   
  73060.     <->    spsPointer
  73061.    
  73062. Other Parameters Affected
  73063.            spByteLanes
  73064.  
  73065. The trap macro SFindStruct returns a pointer to the data structure defined by spId in
  73066. the sResource list pointed to by spsPointer.
  73067.  
  73068. æKY SReadStruct
  73069. æFc Slots.h
  73070. æT Function
  73071. æD pascal OSErr SReadStruct(SpBlockPtr spBlkPtr); 
  73072. æDT OSErr myVariable = SReadStruct((SpBlockPtr) spBlkPtr);
  73073. æRI V-446
  73074. æC 
  73075. Trap macro: _SReadStruct
  73076.  
  73077. Required Parameters
  73078.     -->    spsPointer
  73079.     -->    spSize
  73080.     -->    spResult
  73081.  
  73082. Other Parameter Affected
  73083.            spByteLanes
  73084.  
  73085. The trap macro sReadStruct copies a structure of size spSize from the sResource list
  73086. pointed to by spsPointer  into a new block allocated by the calling program and
  73087. pointed to by spResult.
  73088.  
  73089. æKY SVersion
  73090. æFc Slots.h
  73091. æT Function
  73092. æD pascal OSErr SVersion(SpBlockPtr spBlkPtr); 
  73093. æDT OSErr myVariable = SVersion((SpBlockPtr) spBlkPtr);
  73094. æRI VI
  73095. æC 
  73096. You can use the sVersion function to determine which version of the Slot Manager
  73097. is in use by the Operating System.
  73098.  
  73099. FUNCTION sVersion (spBlkPtr: SpBlockPtr) : OSErr;
  73100.  
  73101. Parameter block
  73102.   ¨    spResult  long  Slot Manager version number
  73103.   ¨    spsPointer  long  pointer to the sResource 
  73104.  
  73105. The sVersion routine returns in the spResult parameter the version number of the
  73106. Slot Manager. The system software version 7.0 Slot Manager returns version
  73107. number 1 for a RAM-based Slot Manager and version number 2 for a ROM-based Slot
  73108. Manager. Older versions of the Slot Manager do not recognize the sVersion
  73109. function and return the nonfatal error –338, smSelOOBErr: Selector is out of
  73110. bounds. The sVersion function returns all zeros in the spsPointer parameter.
  73111.  
  73112. æKY SetSRsrcState
  73113. æFc Slots.h
  73114. æT Function
  73115. æD pascal OSErr SetSRsrcState(SpBlockPtr spBlkPtr); 
  73116. æDT OSErr myVariable = SetSRsrcState((SpBlockPtr) spBlkPtr);
  73117. æC 
  73118.  
  73119. æKY InsertSRTRec
  73120. æFc Slots.h
  73121. æT Function
  73122. æD pascal OSErr InsertSRTRec(SpBlockPtr spBlkPtr); 
  73123. æDT OSErr myVariable = InsertSRTRec((SpBlockPtr) spBlkPtr);
  73124. æRI VI
  73125. æC 
  73126. Parameter block
  73127.   Æ    spsPointer  long  NIL
  73128.   Æ    spParamData  long  flags
  73129.   Æ    spIOReserved  word  reserved
  73130.   Æ    spRefNum  word  sResource Table reference number
  73131.   Æ    spSlot  byte  slot number
  73132.   Æ    spID  byte  structure ID
  73133.   Æ    spExtDev  byte  ID of the external device
  73134.  
  73135. The InsertSRTRec function adds an sResource slot resource to the Slot Resource
  73136. Table. You can use the function to restore a slot resource that was deleted from
  73137. the Slot Resource Table with the SDeleteSRTRec function, described in Volume V.
  73138. If, for example, the user makes a selection in the Monitors control panel that
  73139. requires your video card to switch to a new slot resource that was deleted by
  73140. the PrimaryInit code, you can use the InserSRTRec function to restore that slot
  73141. resource.
  73142.  
  73143. You specify a slot resource with the spSlot, spID, and spExtDev parameters. You
  73144. must set the spsPointer to all zeros. Set the spParamData parameter to 1 to
  73145. disable the restored slot resource or to 0 to enable it.
  73146.  
  73147. If you place a valid device driver reference number in the spRefNum parameter,
  73148. then the Slot Manager updates the dCtlDevBase field in that device driver’s
  73149. Device Control Entry data structure (that is, in the Device Control Entry that
  73150. has that  device driver reference number in the dCtlRefNum field). The
  73151. dCtlDevBase field contains the base address of the memory buffer or data
  73152. provided by the slot resource that is used by that device driver. The Slot
  73153. Manager calculates this address from the contents of the MinorBaseOS or
  73154. MajorBaseOS field in the sResource slot resource for that slot resource, using a
  73155. format that it determines from the value of bit 2 (the f32BitMode flag) in the
  73156. sRsrc_Flags field of the slot resource. The following table shows how the Slot
  73157. Manager determines what format to use for this address:
  73158.  
  73159. sRsrc_Flags     MinorBaseOS   MajorBaseOS   Address Format   Address Type
  73160.  
  73161. Field missing   $xxxxx        Any or none   $Fssx xxxx       1 MB address space;
  73162. can be used in 
  73163.                                                              either 24-bit 
  73164.                                                              or 32-bit mode 
  73165. Field missing   None          $xxxxxx       $sxxx xxxx       Super slot space 
  73166. Bit 2 is 0      $xxxxx        Any or none   $Fssx xxxx       1 MB slot space 
  73167. Bit 2 is 0      None          $xxxxxx       $sxxx xxxx       Super slot space 
  73168. Bit 2 is 1      $xxxxxx       Any or none   $Fsxx xxxx       Standard slot space
  73169.                                                              (32-bit minor
  73170.                                                              base address)
  73171. Bit 2 is 1      None          $xxxxxxx      $sxxx xxxx       Super slot space
  73172.                                                              (32-bit major
  73173.                                                              base address)
  73174.  
  73175. s: slot number
  73176. x: any value
  73177.  
  73178. The Device Control Entry data structure is described in the Device Manager
  73179. chapters of Volumes II and V. Slot resources are described in the NuBus Card
  73180. Firmware chapter of Designing Cards and Drivers for the Macintosh Family.
  73181.  
  73182.  
  73183. Assembly-Language Information:
  73184.  
  73185. Structure of Slot Manager Parameter Block
  73186.  
  73187.     spResult      long  result
  73188.     spsPointer    long  address of structure 
  73189.     spSize        long  size of structure
  73190.     spOffsetData  long  offset/data field
  73191.     spIOFileName  long  reserved for Slot Manager
  73192.     spsExecPBlk   long  address of sExec parameter block
  73193.     spParamData   long  flags
  73194.     spMisc        long  reserved for Slot Manager
  73195.     spReserved    long  reserved for future expansion
  73196.     spIOReserved  word  reserved for Slot Manager
  73197.     spRefNum      word  Slot Resource Table reference number
  73198.     spCategory    word  Category field of sRsrcType entry in sResource
  73199.     spCType       word  cType field of sRsrcType entry in sResource
  73200.     spDrvrSW      word  DrvrSW field of sRsrcType entry in sResource
  73201.     spDrvrHW      word  DrvrHW field of sRsrcType entry in sResource
  73202.     spTBMask      byte  type bit mask
  73203.     spSlot        byte  slot number
  73204.     spID          byte  structure ID
  73205.     spExtDev      byte  ID of the external device
  73206.     spHwDev       byte   ID of the hardware device.
  73207.     spByteLanes   byte  bytelanes from card ROM format block
  73208.     spFlags       byte  reserved for Slot Manager
  73209.     spKey         byte  reserved for Slot Manager
  73210.  
  73211. æKY SGetSRsrc
  73212. æFc Slots.h
  73213. æT Function
  73214. æD pascal OSErr SGetSRsrc(SpBlockPtr spBlkPtr); 
  73215. æDT OSErr myVariable = SGetSRsrc((SpBlockPtr) spBlkPtr);
  73216. æC 
  73217.  
  73218. æKY SGetTypeSRsrc
  73219. æFc Slots.h
  73220. æT Function
  73221. æD pascal OSErr SGetTypeSRsrc(SpBlockPtr spBlkPtr); 
  73222. æDT OSErr myVariable = SGetTypeSRsrc((SpBlockPtr) spBlkPtr);
  73223. æC 
  73224.  
  73225. æKY SReadInfo
  73226. æFc Slots.h
  73227. æT Function
  73228. æD pascal OSErr SReadInfo(SpBlockPtr spBlkPtr); 
  73229. æDT OSErr myVariable = SReadInfo((SpBlockPtr) spBlkPtr);
  73230. æRI V-446
  73231. æC 
  73232. Trap macro: _SReadInfo
  73233.  
  73234. Required Parameters
  73235.     -->    spSlot
  73236.     -->    spResult
  73237.  
  73238. Other Parameter Affected
  73239.            spSize
  73240.  
  73241. The trap macro SReadInfo reads the sInfo record identified by spSlot into a new
  73242. record allocated by the calling program and pointed to by spResult. Here is the
  73243. structure of the sInfo record:
  73244.  
  73245. TYPE
  73246.   SInfoRecPtr = ^SInfoRecord;
  73247.   SInfoRecord = PACKED RECORD
  73248.                   siDirPtr:        Ptr;         {pointer to directory}
  73249.                   siInitStatusA:   INTEGER;     {initialization error}
  73250.                   siInitStatusV:   INTEGER;     {status returned by }
  73251.                                                 { vendor init code}
  73252.                   siState:         SignedByte;  {initialization state}
  73253.                   siCPUByteLanes:  SignedByte;  {0=[d0..d7], }
  73254.                                                 { 1=[d8..d15],  ...}
  73255.                   siTopOfROM:      SignedByte;  {top of ROM = $FsFFFFFx, }
  73256.                                                 { where x is TopOfROM}
  73257.                   siStatusFlags:   SignedByte;  {bit 0--card is changed}
  73258.                   siTOConstant:    INTEGER;     {timeout constant for }
  73259.                                                 { bus error}
  73260.                   siReserved:      SignedByte;  {reserved}
  73261.                 END;
  73262.  
  73263. Assembly-language note:  The sInfo record has the following structure
  73264.                          in assembly language:
  73265.  
  73266.                            siDirPtr        Pointer to sResource directory (long)
  73267.                            siInitStatusA   Fundamental error (word)
  73268.                            siInitStatusV   Status returned by vendor init
  73269.                                            code (word)
  73270.                            siState         Initialization state—primary,
  73271.                                            secondary (byte)
  73272.                            siCPUByteLanes  Each bit set signifies a byte lane
  73273.                                            used (byte)
  73274.                            siTopOfROM      x such that Top of ROM = $FsFFFFFx
  73275.                                            (byte)
  73276.                            siStatusFlags   Bit 0 indicates if card has been
  73277.                                            changed (byte)
  73278.                            siTOConst       Timeout constant for bus error (word)
  73279.                            siReserved      Reserved—must be 0 (byte)
  73280.                            sInfoRecSize    Size of sInfo record
  73281.  
  73282. The siDirPtr field of the sInfo record contains a pointer to the sResource directory
  73283. in the configuration ROM.  The siInitStatusA field indicates the result of efforts to
  73284. initialize the card.  A zero value indicates that the card is installed and operational.
  73285.  A non-zero value is the Slot Manager error code indicating why the card could not be
  73286. used.
  73287.  
  73288. The siInitStatusV field contains the value returned by the card's primary initialization
  73289. code (in the seStatus field of the seBlock).  Negative values cause the card to fail
  73290. initialization.  Zero or positive values indicate that the card is operational.
  73291.  
  73292. The siState field is used internally to indicate what initialization steps have
  73293. occurred so far.
  73294.  
  73295. The siCPUByteLanes field indicate which byte lanes are used by the card.
  73296. The siTopOfROM field gives the last nibble of the address of the actual ByteLanes
  73297. value in the fHeader record.
  73298.  
  73299. The siStatusFlags field gives status information about the slot.  Currently only the
  73300. fCardIsChanged bit has meaning.  A value of 1 indicates that the board ID of the
  73301. installed card did not match the ID saved in parameter RAM—in other words, the card
  73302. has been changed.
  73303.  
  73304. The siTOConstant field contains the number of retries that will be performed when a
  73305. bus error occurs while accessing the declaration ROM.  It defaults to 100, but may be
  73306. set to another value with the TimeOut field in the board sResource of the card.
  73307.  
  73308. The siReserved field is reserved and should have a value of 0.
  73309.  
  73310. æKY SReadPRAMRec
  73311. æFc Slots.h
  73312. æT Function
  73313. æD pascal OSErr SReadPRAMRec(SpBlockPtr spBlkPtr); 
  73314. æDT OSErr myVariable = SReadPRAMRec((SpBlockPtr) spBlkPtr);
  73315. æRI V-448
  73316. æC 
  73317. Trap macro: _SReadPRAMRec
  73318.  
  73319. Required Parameters
  73320.     -->    spSlot
  73321.     -->    spResult
  73322.  
  73323. Other Parameter Affected
  73324.            spSize
  73325.  
  73326. The trap macro SReadPRAMRec copies the sPRAM record data for the slot identified by
  73327. spSlot to a new record allocated by the calling program and pointed to by spResult.
  73328.  
  73329. One sPRAM record for each slot resides in the Macintosh II parameter RAM. The sPRAM
  73330. record is initialized during startup by InitsPRAMRecs, described below under “Advanced
  73331. Routines”.  Here is its structure:
  73332.  
  73333. TYPE
  73334.   SPRAMRecPtr = ^SPRAMRecord;
  73335.   SPRAMRecord = PACKED RECORD
  73336.                   boardID:     INTEGER;       {Apple-defined card }
  73337.                                               { identification}
  73338.                   vendorUse1:  SignedByte;    {reserved for vendor use}
  73339.                   vendorUse2:  SignedByte;    {reserved for vendor use}
  73340.                   vendorUse3:  SignedByte;    {reserved for vendor use}
  73341.                   vendorUse4:  SignedByte;    {reserved for vendor use}
  73342.                   vendorUse5:  SignedByte;    {reserved for vendor use}
  73343.                   vendorUse6:  SignedByte;    {reserved for vendor use}
  73344.                 END;
  73345.  
  73346. Assembly-language note:  The sPRAM record has the following structure in
  73347.                          assembly language:
  73348.  
  73349.                            boardID     Apple-defined card indentification (word)
  73350.                            vendorUse1  Reserved for vendor use (byte)
  73351.                            vendorUse2  Reserved for vendor use (byte)
  73352.                            vendorUse3  Reserved for vendor use (byte)
  73353.                            vendorUse4  Reserved for vendor use (byte)
  73354.                            vendorUse5  Reserved for vendor use (byte)
  73355.                            vendorUse6  Reserved for vendor use (byte)
  73356.  
  73357. If a card is removed from its slot, the corresponding sPRAM record is cleared at the
  73358. next system startup. If a different card is plugged back into the slot, the corresponding
  73359. sPRAM record is reinitialized. A flag is set each time an sPRAM record is initialized,
  73360. to alert the Start Manager.
  73361.  
  73362. æKY SPutPRAMRec
  73363. æFc Slots.h
  73364. æT Function
  73365. æD pascal OSErr SPutPRAMRec(SpBlockPtr spBlkPtr); 
  73366. æDT OSErr myVariable = SPutPRAMRec((SpBlockPtr) spBlkPtr);
  73367. æRI V-449
  73368. æC 
  73369. Trap macro: _SPutPRAMRec
  73370.  
  73371. Required Parameters
  73372.     -->    spSlot
  73373.     -->    spsPointer
  73374.  
  73375. The trap macro SPutPRAMRec copies the logical data from the block referenced by
  73376. spsPointer into the sPRAM record for the slot identified by spSlot.  This updates the
  73377. Macintosh PRAM for that slot.  The sPRAM record is defined above under SReadPRAMRec. 
  73378. In this record, the field boardId is an Apple-defined field and is protected during
  73379. execution of SPutPRAMRec.
  73380.  
  73381. æKY SReadFHeader
  73382. æFc Slots.h
  73383. æT Function
  73384. æD pascal OSErr SReadFHeader(SpBlockPtr spBlkPtr); 
  73385. æDT OSErr myVariable = SReadFHeader((SpBlockPtr) spBlkPtr);
  73386. æRI V-449
  73387. æC 
  73388. Trap macro: _SReadFHeader
  73389.  
  73390. Required Parameters
  73391.     -->    spSlot
  73392.     -->    spResult
  73393.  
  73394. Other Parameters Affected
  73395.            spsPointer
  73396.            spByteLanes
  73397.            spSize
  73398.            spOffsetData
  73399.  
  73400. The trap macro SReadFHeader copies the format block data for the slot designated by
  73401. spSlot to an FHeader record allocated by the calling program and pointed to by spResult.
  73402. Here is the structure of FHeader:
  73403.  
  73404. TYPE
  73405.   FHeaderRecPtr = ^FHeaderRec;
  73406.   FHeaderRec    = PACKED RECORD
  73407.                     fhDIROffset: LONGINT;     {offset to directory}
  73408.                     fhLength:    LONGINT;     {length of ROM}
  73409.                     fhCRC:       LONGINT;     {CRC}
  73410.                     fhROMRev:    SignedByte;  {revision of ROM}
  73411.                     fhFormat:    SignedByte;  {format - 2}
  73412.                     fhTstPat:    LONGINT;     {test pattern}
  73413.                     fhReserved:  SignedByte;  {reserved}
  73414.                     fhByteLanes: SignedByte;  {ByteLanes}
  73415.                   END;
  73416.  
  73417. Assembly-language note:  The FHeader record has the following structure in
  73418.                          assembly language:
  73419.  
  73420.                            fhDIROffset  Offset to sResource directory (long)
  73421.                            fhLength     Length of card’s declaration ROM (long)
  73422.                            fhCRC        Declaration ROM checksum (long)
  73423.                            fhROMRev     ROM revision number (byte)
  73424.                            fhFormat     ROM format number (byte)
  73425.                            fhTstPat     Test Pattern (long)
  73426.                            fhReserved   Reserved (byte)
  73427.                            fhByteLanes  Byte lanes used (byte)
  73428.                            fhSize       Size of the FHeader record
  73429.  
  73430. The fHeader record exists at the highest address of a card’s declaration ROM, and
  73431. should therefore be visible at the highest address in the card’s slot space.  The
  73432. Slot Manager uses the fHeader record to verify that a card is installed in the slot,
  73433. to determine its physical connection to NuBus (which byte lanes are used), and to
  73434. locate the sResource directory.
  73435.  
  73436. The fhDIROffset field of the fHeader record is a self-relative signed 24-bit offset
  73437. to the sResource directory.  The high order byte must be 0, or a card initialization
  73438. error occurs.
  73439.  
  73440. The fhLength field gives the size of the configuration ROM.
  73441.  
  73442. The fhCRC field gives the cyclic redundancy check (CRC) value of the declaration ROM.
  73443.  The CRC value itself is taken as zero in the CRC calculation.
  73444.  
  73445. The fhRomRev field gives the revision level of this declaration ROM.  Values greater
  73446. than 9 cause a card initialization error.
  73447.  
  73448. The fhFormat field identifies the format of the configuration ROM.  Only the value 1
  73449. (appleFormat ) is currently recognized as valid.
  73450.  
  73451. The fhTstPat field is used to verify that the fhByteLanes field is correct.
  73452.  
  73453. The fhReserved field must be zero.
  73454.  
  73455. The fhByteLanes field indicates what NuBus byte lanes are used by the card.  Byte
  73456. lanes are described in the “Access to Address Space” chapter of “Designing Cards and
  73457. Drivers for Macintosh II and Macintosh SE.”
  73458.  
  73459. æKY SNextSRsrc
  73460. æFc Slots.h
  73461. æT Function
  73462. æD pascal OSErr SNextSRsrc(SpBlockPtr spBlkPtr); 
  73463. æDT OSErr myVariable = SNextSRsrc((SpBlockPtr) spBlkPtr);
  73464. æRI V-443
  73465. æC 
  73466. Trap macro: _SNextsRsrc
  73467.  
  73468. Required Parameters
  73469.     <->    spSlot
  73470.     <->    spId
  73471.     <->    spExtDev
  73472.     <--    spsPointer
  73473.     <--    spRefNum
  73474.     <--    spIOReserved
  73475.     <--    spCategory
  73476.     <--    spCType
  73477.     <--    spDrvrSW
  73478.     <--    spDrvrHW
  73479.     <--    spHWDev
  73480.  
  73481. Starting from a given slot number spSlot, sResource list identification number spId,
  73482. and external device identifier spExtDev, the trap macro SNextsRsrc returns the slot
  73483. number, sResource list identification number, sResource type
  73484. (category, cType, software, and hardware), driver reference number (spRefNum), and
  73485. Slot Resource Table ioReserved field (spIOReserved) for the next sResource.  If there
  73486. are no more sResources, SNextsRsrc returns a nonfatal error status. This routine can
  73487. be used to determine the set of all sResources in a given slot card or NuBus configuration.
  73488.  
  73489. æKY SNextTypeSRsrc
  73490. æFc Slots.h
  73491. æT Function
  73492. æD pascal OSErr SNextTypeSRsrc(SpBlockPtr spBlkPtr); 
  73493. æDT OSErr myVariable = SNextTypeSRsrc((SpBlockPtr) spBlkPtr);
  73494. æRI V-443
  73495. æC 
  73496. Trap macro: _SNextTypesRsrc
  73497.  
  73498. Required Parameters
  73499.     <->    spSlot
  73500.     <->    spId
  73501.     <->    spExtDev
  73502.     -->    spTBMask
  73503.     <--    spsPointer
  73504.     <--    spRefNum
  73505.     <--    spIOReserved
  73506.     <->    spCategory
  73507.     <->    spCType
  73508.     <->    spDrvrSW
  73509.     <->    spDrvrHW
  73510.     <->    spHWDev
  73511.  
  73512. Given an sResource type (category, cType, software, and hardware) and spTBMask, and
  73513. starting from a given slot number spSlot and sResource list identification number
  73514. spId, the trap macro SNextTypesRsrc returns the slot number spSlot, sResource list
  73515. identification number spId, sResource type, driver reference number (spRefNum), and
  73516. Slot Resource Table ioReserved field (spIOReserved) for the next sResource of that
  73517. type, as masked. If there are no more sResources of that type, SNextTypesRsrc returns
  73518. a nonfatal error report.
  73519.  
  73520. The spTBMask field lets you mask off specific fields of the sResource type that you
  73521. don’t care about, by setting any of bits 0–3. Bit 3 masks off the spCategory field;
  73522. bit 2 the spCType field; bit 1 the spDrvrSW field; and bit 0 the spDrvrHW field.
  73523.  
  73524. This procedure behaves the same as sNextsRsrc except that it returns information only
  73525. about sResources of the specified type.
  73526.  
  73527. æKY SRsrcInfo
  73528. æFc Slots.h
  73529. æT Function
  73530. æD pascal OSErr SRsrcInfo(SpBlockPtr spBlkPtr); 
  73531. æDT OSErr myVariable = SRsrcInfo((SpBlockPtr) spBlkPtr);
  73532. æRI V-442
  73533. æC 
  73534. Assembly-language note:  All Slot Manager routines return a status result in
  73535.                          the low-order word of register D0 after execution. A
  73536.                          D0 value of zero indicates successful execution. Other
  73537.                          D0 values are listed under “Status Results” later in
  73538.                          this section. All routines report fatal errors (those
  73539.                          that halt program execution); some may also report
  73540.                          nonfatal errors. The description of each routine
  73541.                          specifies if it can return status values indicating
  73542.                          nonfatal errors.
  73543.  
  73544. Trap macro: _SRsrcInfo
  73545.  
  73546. Required Parameters
  73547.     <--    spsPointer
  73548.     <--    spIOReserved
  73549.     <--    spRefNum
  73550.     <--    spCategory
  73551.     <--    spCType
  73552.     <--    spDrvrSW
  73553.     <--    spDrvrHW
  73554.     -->    spSlot
  73555.     -->    spId
  73556.     -->    spExtDev
  73557.     <--    spHWDev
  73558.  
  73559. The trap macro SRsrcInfo returns an sResource list pointer (spsPointer), plus the
  73560. sResource type (category, cType, software, and hardware), driver reference number
  73561. (spRefNum), and Slot Resource Table ioReserved field (spIOReserved) for the  sResource
  73562. specified by the slot number spSlot, sResource list identification number spId, and
  73563. external device identifier spExtDev.  This call is most often used to return the
  73564. driver reference number.
  73565.  
  73566. æKY SCkCardStat
  73567. æFc Slots.h
  73568. æT Function
  73569. æD pascal OSErr SCkCardStat(SpBlockPtr spBlkPtr); 
  73570. æDT OSErr myVariable = SCkCardStat((SpBlockPtr) spBlkPtr);
  73571. æRI V-450
  73572. æC 
  73573. Trap macro: _SCkCardStatus
  73574.  
  73575. Required Parameter
  73576.     -->    spSlot
  73577.  
  73578. Other Parameter Affected
  73579.            spResult
  73580.  
  73581. The trap macro SCkCardStatus checks the InitStatusA field of the sInfo record of the
  73582. slot designated by spSlot, which also reflects the value of InitStatusV. If this
  73583. field contains a nonzero value, SCkCardStatus returns a zero value.  The sInfo record
  73584. is described above under SReadInfo.  The sCkCardStatus routine can return nonfatal
  73585. error reports.
  73586.  
  73587. æKY SReadDrvrName
  73588. æFc Slots.h
  73589. æT Function
  73590. æD pascal OSErr SReadDrvrName(SpBlockPtr spBlkPtr); 
  73591. æDT OSErr myVariable = SReadDrvrName((SpBlockPtr) spBlkPtr);
  73592. æRI V-444
  73593. æC 
  73594. Trap macro: _SReadDrvrName
  73595.  
  73596. Required Parameters
  73597.     -->    spSlot
  73598.     -->    spId
  73599.     -->    spResult
  73600.  
  73601. Other Parameters Affected
  73602.  
  73603.            spSize
  73604.            spsPointer
  73605.  
  73606. The trap macro SReadDrvrName reads the name of the sResource corresponding to the
  73607. slot number spSlot and sResource list identification number spId, prefixes a period
  73608. to the value of the cString and converts its type to Str255. It then reads the result
  73609. into a Pascal string variable declared by the calling program and pointed to by
  73610. spResult. The final driver name is compatible with the Open routine.
  73611.  
  73612. æKY SFindDevBase
  73613. æFc Slots.h
  73614. æT Function
  73615. æD pascal OSErr SFindDevBase(SpBlockPtr spBlkPtr); 
  73616. æDT OSErr myVariable = SFindDevBase((SpBlockPtr) spBlkPtr);
  73617. æRI V-451
  73618. æC 
  73619. Trap macro: _SFindDevBase
  73620.  
  73621. Required Parameters
  73622.     -->    spSlot
  73623.     -->    spId
  73624.     <--    spResult
  73625.  
  73626. The trap macro SFindDevBase returns a pointer in spResult to the base of a device
  73627. whose slot number is in spSlot and whose sResource id is in spId.  The base address
  73628. of a device may be in either slot or superslot space but not in both.  Slot or superslot
  73629. slot spaces are discussed in the book “Designing Cards and Drivers for Macintosh II
  73630. and Macintosh SE.”
  73631.  
  73632. æKY SFindBigDevBase
  73633. æFc Slots.h
  73634. æT Function
  73635. æD pascal OSErr SFindBigDevBase(SpBlockPtr spBlkPtr); 
  73636. æDT OSErr myVariable = SFindBigDevBase((SpBlockPtr) spBlkPtr);
  73637. æC 
  73638.  
  73639. æKY SGetSRsrcPtr
  73640. æFc Slots.h
  73641. æT Function
  73642. æD pascal OSErr SGetSRsrcPtr(SpBlockPtr spBlkPtr); 
  73643. æDT OSErr myVariable = SGetSRsrcPtr((SpBlockPtr) spBlkPtr);
  73644. æC 
  73645.  
  73646. æKY InitSDeclMgr
  73647. æFc Slots.h
  73648. æT Function
  73649. æD pascal OSErr InitSDeclMgr(SpBlockPtr spBlkPtr); 
  73650. æDT OSErr myVariable = InitSDeclMgr((SpBlockPtr) spBlkPtr);
  73651. æMM
  73652. æRI V-451
  73653. æC 
  73654. Trap macro: _InitSDeclMgr
  73655.  
  73656. The trap macro InitSDeclMgr initializes the Slot Manager. The contents of the parameter
  73657. block are undefined. This procedure allocates the sInfo array and checks each slot
  73658. for a card. If a card is not present, an error is logged in the initStatusA field of
  73659. the sInfoRecord for that slot; otherwise the card’s firmware is validated, and the
  73660. resulting data is placed in the slot’s sInfoRecord. The sInfoRecord is described
  73661. above under SReadInfo.
  73662.  
  73663. æKY SPrimaryInit
  73664. æFc Slots.h
  73665. æT Function
  73666. æD pascal OSErr SPrimaryInit(SpBlockPtr spBlkPtr); 
  73667. æDT OSErr myVariable = SPrimaryInit((SpBlockPtr) spBlkPtr);
  73668. æMM
  73669. æRI V-452
  73670. æC 
  73671. Trap macro: _SPrimaryInit
  73672.  
  73673. Required Parameter
  73674.     -->    spFlags
  73675.  
  73676. The trap macro SPrimaryInit initializes each slot having an sPrimaryInit record. It
  73677. passes the spFlags byte to the initialization code via seFlags.  Within that byte the
  73678. fWarmStart bit should be set to 1 if a warm start is being performed.
  73679.  
  73680. æKY SCardChanged
  73681. æFc Slots.h
  73682. æT Function
  73683. æD pascal OSErr SCardChanged(SpBlockPtr spBlkPtr); 
  73684. æDT OSErr myVariable = SCardChanged((SpBlockPtr) spBlkPtr);
  73685. æRI V-452
  73686. æC 
  73687. Trap macro: _SCardChanged
  73688.  
  73689. Required Parameters
  73690.     -->    spSlot
  73691.     <--    spResult
  73692.  
  73693. The trap macro SCardChanged returns a value of true in spResult if the card in slot
  73694. spSlot has been changed (that is, if its sPRAMRecord has been initialized); otherwise
  73695. it returns false.
  73696.  
  73697. æKY SExec
  73698. æFc Slots.h
  73699. æT Function
  73700. æD pascal OSErr SExec(SpBlockPtr spBlkPtr); 
  73701. æDT OSErr myVariable = SExec((SpBlockPtr) spBlkPtr);
  73702. æMM
  73703. æRI V-452
  73704. æC 
  73705. Trap macro: _SExec
  73706.  
  73707. Required Parameters
  73708.     -->    spsPointer
  73709.     -->    spId
  73710.     -->    spsExecPBlk
  73711.  
  73712. Other parameters affected:
  73713.            spResult
  73714.  
  73715. The trap macro SExec loads an sExecBlock from the sResource list pointed to by spsPointer
  73716. and identified by spId to the current heap zone, checks its revision level, checks
  73717. its CPU field, and executes the code. The status is returned in seStatus.  The spsExecPBlk
  73718. field is presumed to hold a pointer to an sExecBlock (described in the “Slot Manager
  73719. Routines” section earlier in this chapter), and is passed to the sExec block code in
  73720. register A0.
  73721.  
  73722. æKY SOffsetData
  73723. æFc Slots.h
  73724. æT Function
  73725. æD pascal OSErr SOffsetData(SpBlockPtr spBlkPtr); 
  73726. æDT OSErr myVariable = SOffsetData((SpBlockPtr) spBlkPtr);
  73727. æRI V-452
  73728. æC 
  73729. Trap macro: _SOffsetData
  73730.  
  73731. Required Parameters
  73732.     -->    spsPointer
  73733.     -->    spId
  73734.     <--    spOffsetData
  73735.     <--    spByteLanes
  73736.  
  73737. Other Parameters Affected
  73738.            spResult
  73739.            spFlags
  73740.  
  73741. The trap macro SOffsetData returns (in spOffsetData) the contents of the
  73742. offset/data field from the sResource list identified by spId and pointed to by spsPointer.
  73743. The parameter spsPointer returns a pointer to the fields’s identification number in
  73744. the sResource list.
  73745.  
  73746. æKY SInitPRAMRecs
  73747. æFc Slots.h
  73748. æT Function
  73749. æD pascal OSErr SInitPRAMRecs(SpBlockPtr spBlkPtr); 
  73750. æDT OSErr myVariable = SInitPRAMRecs((SpBlockPtr) spBlkPtr);
  73751. æC 
  73752. Trap macro: _InitPRAMRecs
  73753.  
  73754. The trap macro InitPRAMRecs scans every slot and checks its BoardId value against the
  73755. value stored for it in its sPRAM record. If the values do not match, then the CardIsChanged
  73756. flag is set and the Board sResource list is searched for an sPRAMInitRecord. If one
  73757. is found, the sPRAMRecord for the slot is initialized with this data; otherwise it is
  73758. initialized with all zeros.
  73759.  
  73760. æKY SReadPBSize
  73761. æFc Slots.h
  73762. æT Function
  73763. æD pascal OSErr SReadPBSize(SpBlockPtr spBlkPtr); 
  73764. æDT OSErr myVariable = SReadPBSize((SpBlockPtr) spBlkPtr);
  73765. æRI V-453
  73766. æC 
  73767. Trap macro: _SReadPBSize
  73768.  
  73769. Required Parameters
  73770.     -->    spsPointer
  73771.     -->    spId
  73772.     -->    spFlags
  73773.     <--    spSize
  73774.     <--    spByteLanes
  73775.  
  73776. Other Parameter Affected
  73777.            spResult
  73778.  
  73779. The trap macro SReadPBSize reads the physical block size of the sBlock pointed to by
  73780. spsPointer and identified by spId. It also checks to see that the upper byte is 0 if
  73781. the fckReserved flag is set. The parameter spsPointer points to the resulting logical
  73782. block when SReadPBSize is done.
  73783.  
  73784. æKY SCalcStep
  73785. æFc Slots.h
  73786. æT Function
  73787. æD pascal OSErr SCalcStep(SpBlockPtr spBlkPtr); 
  73788. æDT OSErr myVariable = SCalcStep((SpBlockPtr) spBlkPtr);
  73789. æRI V-453
  73790. æC 
  73791. Trap macro: _SCalcStep
  73792.  
  73793. Parameters Required
  73794.     -->    spsPointer
  73795.     -->    spByteLanes
  73796.     -->    spFlags
  73797.     <--    spResult
  73798.  
  73799. The trap macro SCalcStep calculates the field sizes in the block pointed to by spBlkPtr.
  73800. It is used for stepping through the card firmware one field at a time.  If the fConsecBytes
  73801. flag is set it calculates the step value for consecutive bytes; otherwise it calculates
  73802. it for consecutive IDs.
  73803.  
  73804. æKY SInitSRsrcTable
  73805. æFc Slots.h
  73806. æT Function
  73807. æD pascal OSErr SInitSRsrcTable(SpBlockPtr spBlkPtr); 
  73808. æDT OSErr myVariable = SInitSRsrcTable((SpBlockPtr) spBlkPtr);
  73809. æC 
  73810. Trap macro: _InitsRsrcTable
  73811.  
  73812. The trap macro InitsRsrcTable initializes the Slot Resource Table. It scans each slot
  73813. and inserts the slot, type, sRsrcId, sRsrcPtr, and HWDevID values into the table for
  73814. every sResource. It sets all other fields to zero.  The contents of the parameter
  73815. block are undefined.
  73816.  
  73817. æKY SSearchSRT
  73818. æFc Slots.h
  73819. æT Function
  73820. æD pascal OSErr SSearchSRT(SpBlockPtr spBlkPtr); 
  73821. æDT OSErr myVariable = SSearchSRT((SpBlockPtr) spBlkPtr);
  73822. æRI V-454
  73823. æC 
  73824. Trap macro: _SSearchSRT
  73825.  
  73826. Parameters Required
  73827.     -->    spSlot
  73828.     -->    spId
  73829.     -->    spExtDev
  73830.     -->    spFlags
  73831.     -->    spsPointer
  73832.  
  73833. The trap macro SSearchSRT searches the Slot Resource Table for the record corresponding
  73834. to the sResource in slot spSlot with list spId and external device identifier spExtDev,
  73835. and returns a pointer to it in spsPointer.  If the fckForNext bit of spFlags has a
  73836. value of 0, it searches for that record; if it has a value of 1, it searches for the
  73837. next record.
  73838.  
  73839. æKY SUpdateSRT
  73840. æFc Slots.h
  73841. æT Function
  73842. æD pascal OSErr SUpdateSRT(SpBlockPtr spBlkPtr); 
  73843. æDT OSErr myVariable = SUpdateSRT((SpBlockPtr) spBlkPtr);
  73844. æRI V-454
  73845. æC 
  73846. Trap macro: _SUpdateSRT
  73847.  
  73848. Parameters Required
  73849.     -->    spSlot
  73850.     -->    spId
  73851.     -->    spExtDev
  73852.     -->    spRefNum
  73853.     -->    spIOReserved
  73854.  
  73855. Other Parameters Affected
  73856.            spsPointer
  73857.            spFlags
  73858.            spSize
  73859.            spResult
  73860.  
  73861. The trap macro SUpdateSRT updates the Slot Resource Table records spRefNum and spIOReserved
  73862. with information about the sResource in slot spSlot with list spId and external
  73863. device identifier spExtDev. This routine is called by IOCore whenever the driver for
  73864. a slot device is opened or closed.
  73865.  
  73866. æKY SCalcSPointer
  73867. æFc Slots.h
  73868. æT Function
  73869. æD pascal OSErr SCalcSPointer(SpBlockPtr spBlkPtr); 
  73870. æDT OSErr myVariable = SCalcSPointer((SpBlockPtr) spBlkPtr);
  73871. æRI V-455
  73872. æC 
  73873. Trap macro: _SCalcSPtr
  73874.  
  73875. Parameters Required
  73876.     -->    spsPointer
  73877.     -->    spOffsetData
  73878.     -->    spByteLanes
  73879.  
  73880. The trap macro SCalcSPtr returns a pointer to a given byte in a card’s declaration
  73881. ROM, given the pointer to a current byte and an offset
  73882. (spOffsetData) in bytes.
  73883.  
  73884. æKY SGetDriver
  73885. æFc Slots.h
  73886. æT Function
  73887. æD pascal OSErr SGetDriver(SpBlockPtr spBlkPtr); 
  73888. æDT OSErr myVariable = SGetDriver((SpBlockPtr) spBlkPtr);
  73889. æMM
  73890. æRI V-455
  73891. æC 
  73892. Trap macro: _SGetDriver
  73893.  
  73894. Parameters Required
  73895.     -->    spSlot
  73896.     -->    spId
  73897.     -->    spExtDev
  73898.     -->    spsExecPBlk
  73899.     <--    spResult
  73900.  
  73901. Other Parameters Affected
  73902.            spFlags
  73903.            spSize
  73904.  
  73905. The trap macro SGetDriver loads the driver corresponding to the sResource designated
  73906. by the slot number spSlot and the sResource list identification number spId into a
  73907. relocatable block on the system heap and returns a handle to it in spResult (referenced
  73908. by A0 in assembly language). The driver can come from either of two sources:
  73909.  
  73910.   •  First, the sResource sLoad directory is checked for a Macintosh
  73911.      sLoadRecord. If one is found, then the sLoad record is loaded into RAM
  73912.      and executed.
  73913.   •  If no sLoad record exists, the sResource sDriver directory is checked for
  73914.      an sDriverRecord. If one is found, then the sDriver record is loaded into
  73915.      RAM.
  73916.  
  73917. æKY SPtrToSlot
  73918. æFc Slots.h
  73919. æT Function
  73920. æD pascal OSErr SPtrToSlot(SpBlockPtr spBlkPtr); 
  73921. æDT OSErr myVariable = SPtrToSlot((SpBlockPtr) spBlkPtr);
  73922. æRI V-451
  73923. æC 
  73924. Trap macro: _SPtrToSlot
  73925.  
  73926. Required Parameters
  73927.     -->    spsPointer
  73928.     <--    spSlot
  73929.  
  73930. The trap macro SPtrToSlot returns in spSlot the slot number of the card whose declaration
  73931. ROM is pointed to by spsPointer.  The value of spsPointer must have the form Fsxx
  73932. xxxx, where s is a slot number.
  73933.  
  73934. æKY SFindSInfoRecPtr
  73935. æFc Slots.h
  73936. æT Function
  73937. æD pascal OSErr SFindSInfoRecPtr(SpBlockPtr spBlkPtr); 
  73938. æDT OSErr myVariable = SFindSInfoRecPtr((SpBlockPtr) spBlkPtr);
  73939. æRI V-455
  73940. æC 
  73941. Trap macro: _SFindsInfoRecPtr
  73942.  
  73943. Parameters Required
  73944.     -->    spSlot
  73945.     <--    spResult
  73946.  
  73947. The trap macro SFindsInfoRecPtr returns a pointer to the sInfoRecord identified by
  73948. spSlot.  The sInfoRecord is described under SReadInfo.
  73949.  
  73950. æKY SFindSRsrcPtr
  73951. æFc Slots.h
  73952. æT Function
  73953. æD pascal OSErr SFindSRsrcPtr(SpBlockPtr spBlkPtr); 
  73954. æDT OSErr myVariable = SFindSRsrcPtr((SpBlockPtr) spBlkPtr);
  73955. æRI V-456
  73956. æC 
  73957. Trap macro: _SFindsRsrcPtr
  73958.  
  73959. Parameters Required
  73960.     <--    spsPointer
  73961.     -->    spSlot
  73962.     -->    spId
  73963.  
  73964. Other Parameter Affected
  73965.            spResult
  73966.  
  73967. The trap macro SFindsRsrcPtr returns a pointer to the sRsrc list for the sRsrc identified
  73968. by spSlot, spID, and spExtDev.
  73969.  
  73970. æKY SDeleteSRTRec
  73971. æFc Slots.h
  73972. æT Function
  73973. æD pascal OSErr SDeleteSRTRec(SpBlockPtr spBlkPtr); 
  73974. æDT OSErr myVariable = SDeleteSRTRec((SpBlockPtr) spBlkPtr);
  73975. æRI V-451
  73976. æC 
  73977. Trap macro: _SDeleteSRTRec
  73978.  
  73979. Required Parameters
  73980.     -->    spSlot
  73981.     -->    spId
  73982.     -->    spExtDev
  73983.  
  73984. The trap macro SDeleteSRTRec deletes from the system’s Slot Resource Table the sResource
  73985. defined by spId,spSlot, and spExtDev.
  73986.  
  73987. æKY OpenSlot
  73988. æFc Slots.h
  73989. æT Function
  73990. æD pascal OSErr OpenSlot(ParmBlkPtr paramBlock,Boolean aSync); 
  73991. æDT OSErr myVariable = OpenSlot((ParmBlkPtr) paramBlock,(Boolean) aSync);
  73992. æRI V-425
  73993. æC If the slot sResource serves a single device (for example, a video device),  
  73994. clear all the bits of the ioFlags field and use the following parameter block: 
  73995.  
  73996. Parameter block
  73997.  
  73998.     ->  12  ioCompletion  pointer
  73999.     <-  16  ioResult      word
  74000.     ->  18  ioNamePtr     pointer
  74001.     <-  22  ioRefNum      word
  74002.     ->  27  ioPermssn     byte
  74003.     
  74004.     ->  28  ioMix         pointer
  74005.     ->  32  ioFlags       word
  74006.     ->  34  ioSlot        byte
  74007.     ->  35  ioId          byte
  74008.  
  74009. In the extension fields, ioMix is a pointer reserved for use by the driver  
  74010. open routine.  The ioSlot parameter contains the slot number of the device  
  74011. being opened, in the range 9..$E; if a built-in device is being opened, ioSlot  
  74012. must be 0.  The ioId parameter contains the sResource ID.  Slot numbers and  
  74013. sResources are discussed in the Slot Manager chapter of this volume. 
  74014.  
  74015. If the slot sResource serves more than one device (for example, a chain of disk 
  74016. drives),  set the fMulti bit in the ioFlags field (clearing all other flags bits to 0)  
  74017. and use the following parameter block:
  74018.  
  74019. Parameter block
  74020.  
  74021.     ->  12  ioCompletion  pointer
  74022.     <-  16  ioResult      word
  74023.     ->  18  ioNamePtr     pointer
  74024.     <-  22  ioRefNum      word
  74025.     ->  27  ioPermssn     byte
  74026.     
  74027.     ->  28  ioMix         pointer
  74028.     ->  32  ioFlags       word
  74029.     ->  34  ioSEBlkPtr    pointer
  74030.     
  74031. Here the new parameter ioSEBlkPtr is a pointer to an external parameter block  
  74032. (described in the Slot Manager chapter of this volume) that is customized for  
  74033. the devices installed in the slot.  The pointer value is passed to the driver.
  74034.  
  74035.  
  74036. æKY Sound.h
  74037. æKL Comp3to1
  74038. Comp6to1
  74039. Exp1to3
  74040. Exp1to6
  74041. GetSoundVol
  74042. MACEVersion
  74043. SetSoundVol
  74044. SndAddModifier
  74045. SndChannelStatus
  74046. SndControl
  74047. SndDisposeChannel
  74048. SndDoCommand
  74049. SndDoImmediate
  74050. SndGetBufferStufferLoad
  74051. SndGetMixerLoad
  74052. SndGetSysBeepState
  74053. SndManagerStatus
  74054. SndNewChannel
  74055. SndPauseFilePlay
  74056. SndPlay
  74057. SndPlayDoubleBuffer
  74058. SndSetSysBeepState
  74059. SndSoundManagerVersion
  74060. SndStartFilePlay
  74061. SndStopFilePlay
  74062. SoundDone
  74063. StartSound
  74064. StopSound
  74065.  
  74066. ACEBadCmd
  74067. ACEBadComp
  74068. ACEBadDest
  74069. ACEBadEncode
  74070. ACEMemFull
  74071. ACENilBlock
  74072. ACESuccess
  74073. ampCmd
  74074. AudioSelection
  74075. AudioSelectionPtr
  74076. availableCmd
  74077. bufferCmd
  74078. callBackCmd
  74079. cmpSH
  74080. CmpSoundHeader
  74081. CmpSoundHeaderPtr
  74082. continueCmd
  74083. convertCmd
  74084. dataPointerFlag
  74085. dbBufferEmpty
  74086. dbBufferEmptyMask
  74087. dbBufferExhausted
  74088. dbBufferReady
  74089. dbLastBuffer
  74090. doubleBufferCmd
  74091. eightToThree
  74092. emptyCmd
  74093. extSH
  74094. ExtSoundHeader
  74095. ExtSoundHeaderPtr
  74096. ffMode
  74097. FFSynthPtr
  74098. FFSynthRec
  74099. FirstSoundFormat
  74100. firstSoundFormat
  74101. flushCmd
  74102. freeCmd
  74103. FreeWave[30001]
  74104. freqCmd
  74105. ftMode
  74106. FTSndRecPtr
  74107. FTSoundRec
  74108. FTSynthPtr
  74109. FTSynthRec
  74110. getRateCmd
  74111. howOftenCmd
  74112. infiniteTime
  74113. initChan0
  74114. initChan1
  74115. initChan2
  74116. initChan3
  74117. initChanLeft
  74118. initChanRight
  74119. initCmd
  74120. initMACE3
  74121. initMACE6
  74122. initMono
  74123. initNoLERP
  74124. initNoSRConv
  74125. initSRate22k
  74126. initSRate44k
  74127. initSRateMask
  74128. initStereo
  74129. initStereoMask
  74130. insideCmpSH
  74131. LeftOverBlock
  74132. LeftOverBlockPtr
  74133. LeftOverBlockSize
  74134. loadCmd
  74135. maceToolNum
  74136. midiDataCmd
  74137. midiInitChanFilter
  74138. midiInitRawMode
  74139. midiSynthIn
  74140. midiSynthOut
  74141. ModifierStub
  74142. ModRef
  74143. MOVEL
  74144. notCompressed
  74145. noteCmd
  74146. noteSynth
  74147. nullCmd
  74148. outsideCmpSH
  74149. pauseCmd
  74150. phaseCmd
  74151. quietCmd
  74152. rateCmd
  74153. reInitCmd
  74154. requestNextCmd
  74155. restCmd
  74156. resumeCmd
  74157. sampledSynth
  74158. scaleCmd
  74159. SCStatus
  74160. SCStatusPtr
  74161. SecondSoundFormat
  74162. setPtrBit
  74163. sixToOne
  74164. sixToOnePacketSize
  74165. sizeCmd
  74166. sMgrComp3to1
  74167. sMgrComp6to1
  74168. sMgrExp1to3
  74169. sMgrExp1to6
  74170. sMgrMACEVersion
  74171. sMgrSndChannelStatus
  74172. sMgrSndGetBufferStufferLoad
  74173. sMgrSndGetMixerLoad
  74174. sMgrSndGetSysBeepState
  74175. sMgrSndManagerStatus
  74176. sMgrSndPauseFilePlay
  74177. sMgrSndPlayDoubleBuffer
  74178. sMgrSndSetSysBeepState
  74179. sMgrSndSoundManagerVersion
  74180. sMgrSndStartFilePlay
  74181. sMgrSndStopFilePlay
  74182. sMgrToolNum
  74183. SMStatus
  74184. SMStatusPtr
  74185. SndChannel
  74186. SndCommand
  74187. SndDoubleBuffer
  74188. SndDoubleBufferHeader
  74189. SndDoubleBufferHeaderPtr
  74190. SndDoubleBufferPtr
  74191. SndListPtr
  74192. SndListResource
  74193. soundCmd
  74194. SoundHeader
  74195. SoundHeaderPtr
  74196. soundListRsrc
  74197. StateBlock
  74198. StateBlockPtr
  74199. StateBlockSize
  74200. stdQLength
  74201. stdSH
  74202. swMode
  74203. SWSynthPtr
  74204. SWSynthRec
  74205. syncCmd
  74206. synthCodeRsrc
  74207. sysBeepDisable
  74208. sysBeepEnable
  74209. tempoCmd
  74210. threeToOne
  74211. threeToOnePacketSize
  74212. tickleCmd
  74213. timbreCmd
  74214. Time
  74215. Tone
  74216. totalLoadCmd
  74217. twelthRootTwo
  74218. twoToOne
  74219. unitTypeNoSelection
  74220. unitTypeSeconds
  74221. versionCmd
  74222. waitCmd
  74223. wakeUpCmd
  74224. Wave
  74225. waveInitChannel0
  74226. waveInitChannel1
  74227. waveInitChannel2
  74228. waveInitChannel3
  74229. waveInitChannelMask
  74230. waveTableCmd
  74231. waveTableSynth
  74232.  
  74233. æKY swMode
  74234. æFc Sound.h
  74235. æT #define
  74236. æD #define swMode -1
  74237. æC 
  74238.  
  74239. æKY ftMode
  74240. æFc Sound.h
  74241. æT #define
  74242. æD #define ftMode 1
  74243. æC 
  74244.  
  74245. æKY ffMode
  74246. æFc Sound.h
  74247. æT #define
  74248. æD #define ffMode 0
  74249. æC 
  74250.  
  74251. æKY synthCodeRsrc
  74252. æFc Sound.h
  74253. æT #define
  74254. æD #define synthCodeRsrc 'snth'
  74255. æC 
  74256.  
  74257. æKY soundListRsrc
  74258. æFc Sound.h
  74259. æT #define
  74260. æD #define soundListRsrc 'snd '
  74261. æC 
  74262.  
  74263. æKY noteSynth
  74264. æFc Sound.h
  74265. æT #define
  74266. æD 
  74267. /* synthesizer numbers for SndNewChannel */
  74268.  
  74269. #define noteSynth 1 /*note synthesizer*/
  74270. æC 
  74271.  
  74272. æKY waveTableSynth
  74273. æFc Sound.h
  74274. æT #define
  74275. æD #define waveTableSynth 3 /*wave table synthesizer*/
  74276. æC 
  74277.  
  74278. æKY sampledSynth
  74279. æFc Sound.h
  74280. æT #define
  74281. æD #define sampledSynth 5 /*sampled sound synthesizer*/
  74282. æC 
  74283.  
  74284. æKY midiSynthIn
  74285. æFc Sound.h
  74286. æT #define
  74287. æD #define midiSynthIn 7 /*MIDI synthesizer in*/
  74288. æC 
  74289.  
  74290. æKY midiSynthOut
  74291. æFc Sound.h
  74292. æT #define
  74293. æD #define midiSynthOut 9 /*MIDI synthesizer out*/
  74294. æC 
  74295.  
  74296. æKY midiInitChanFilter
  74297. æFc Sound.h
  74298. æT #define
  74299. æD 
  74300. /* Param2 values */
  74301.  
  74302. #define midiInitChanFilter 0x10 /*set to initialize a MIDI channel*/
  74303. æC 
  74304.  
  74305. æKY midiInitRawMode
  74306. æFc Sound.h
  74307. æT #define
  74308. æD #define midiInitRawMode 0x100 /*set to send raw MIDI data*/
  74309. æC 
  74310.  
  74311. æKY twelthRootTwo
  74312. æFc Sound.h
  74313. æT #define
  74314. æD #define twelthRootTwo 1.05946309434
  74315. æC 
  74316.  
  74317. æKY infiniteTime
  74318. æFc Sound.h
  74319. æT #define
  74320. æD #define infiniteTime 0x7FFFFFFF
  74321. æC 
  74322.  
  74323. æKY nullCmd
  74324. æFc Sound.h
  74325. æT #define
  74326. æD 
  74327. /* command numbers for SndDoCommand */
  74328.  
  74329. #define nullCmd 0
  74330. æC 
  74331.  
  74332. æKY initCmd
  74333. æFc Sound.h
  74334. æT #define
  74335. æD #define initCmd 1
  74336. æC 
  74337.  
  74338. æKY freeCmd
  74339. æFc Sound.h
  74340. æT #define
  74341. æD #define freeCmd 2
  74342. æC 
  74343.  
  74344. æKY quietCmd
  74345. æFc Sound.h
  74346. æT #define
  74347. æD #define quietCmd 3
  74348. æC 
  74349.  
  74350. æKY flushCmd
  74351. æFc Sound.h
  74352. æT #define
  74353. æD #define flushCmd 4
  74354. æC 
  74355.  
  74356. æKY reInitCmd
  74357. æFc Sound.h
  74358. æT #define
  74359. æD #define reInitCmd 5
  74360. æC 
  74361.  
  74362. æKY waitCmd
  74363. æFc Sound.h
  74364. æT #define
  74365. æD #define waitCmd 10
  74366. æC 
  74367.  
  74368. æKY pauseCmd
  74369. æFc Sound.h
  74370. æT #define
  74371. æD #define pauseCmd 11
  74372. æC 
  74373.  
  74374. æKY resumeCmd
  74375. æFc Sound.h
  74376. æT #define
  74377. æD #define resumeCmd 12
  74378. æC 
  74379.  
  74380. æKY callBackCmd
  74381. æFc Sound.h
  74382. æT #define
  74383. æD #define callBackCmd 13
  74384. æC 
  74385.  
  74386. æKY syncCmd
  74387. æFc Sound.h
  74388. æT #define
  74389. æD #define syncCmd 14
  74390. æC 
  74391.  
  74392. æKY emptyCmd
  74393. æFc Sound.h
  74394. æT #define
  74395. æD #define emptyCmd 15
  74396. æC 
  74397.  
  74398. æKY tickleCmd
  74399. æFc Sound.h
  74400. æT #define
  74401. æD #define tickleCmd 20
  74402. æC 
  74403.  
  74404. æKY requestNextCmd
  74405. æFc Sound.h
  74406. æT #define
  74407. æD #define requestNextCmd 21
  74408. æC 
  74409.  
  74410. æKY howOftenCmd
  74411. æFc Sound.h
  74412. æT #define
  74413. æD #define howOftenCmd 22
  74414. æC 
  74415.  
  74416. æKY wakeUpCmd
  74417. æFc Sound.h
  74418. æT #define
  74419. æD #define wakeUpCmd 23
  74420. æC 
  74421.  
  74422. æKY availableCmd
  74423. æFc Sound.h
  74424. æT #define
  74425. æD #define availableCmd 24
  74426. æC 
  74427.  
  74428. æKY versionCmd
  74429. æFc Sound.h
  74430. æT #define
  74431. æD #define versionCmd 25
  74432. æC 
  74433.  
  74434. æKY totalLoadCmd
  74435. æFc Sound.h
  74436. æT #define
  74437. æD #define totalLoadCmd 26
  74438. æC 
  74439.  
  74440. æKY loadCmd
  74441. æFc Sound.h
  74442. æT #define
  74443. æD #define loadCmd 27
  74444. æC 
  74445.  
  74446. æKY scaleCmd
  74447. æFc Sound.h
  74448. æT #define
  74449. æD #define scaleCmd 30
  74450. æC 
  74451.  
  74452. æKY tempoCmd
  74453. æFc Sound.h
  74454. æT #define
  74455. æD #define tempoCmd 31
  74456. æC 
  74457.  
  74458. æKY noteCmd
  74459. æFc Sound.h
  74460. æT #define
  74461. æD #define noteCmd 40
  74462. æC 
  74463.  
  74464. æKY restCmd
  74465. æFc Sound.h
  74466. æT #define
  74467. æD #define restCmd 41
  74468. æC 
  74469.  
  74470. æKY freqCmd
  74471. æFc Sound.h
  74472. æT #define
  74473. æD #define freqCmd 42
  74474. æC 
  74475.  
  74476. æKY ampCmd
  74477. æFc Sound.h
  74478. æT #define
  74479. æD #define ampCmd 43
  74480. æC 
  74481.  
  74482. æKY timbreCmd
  74483. æFc Sound.h
  74484. æT #define
  74485. æD #define timbreCmd 44
  74486. æC 
  74487.  
  74488. æKY waveTableCmd
  74489. æFc Sound.h
  74490. æT #define
  74491. æD #define waveTableCmd 60
  74492. æC 
  74493.  
  74494. æKY phaseCmd
  74495. æFc Sound.h
  74496. æT #define
  74497. æD #define phaseCmd 61
  74498. æC 
  74499.  
  74500. æKY soundCmd
  74501. æFc Sound.h
  74502. æT #define
  74503. æD #define soundCmd 80
  74504. æC 
  74505.  
  74506. æKY bufferCmd
  74507. æFc Sound.h
  74508. æT #define
  74509. æD #define bufferCmd 81
  74510. æC 
  74511.  
  74512. æKY rateCmd
  74513. æFc Sound.h
  74514. æT #define
  74515. æD #define rateCmd 82
  74516. æC 
  74517.  
  74518. æKY continueCmd
  74519. æFc Sound.h
  74520. æT #define
  74521. æD #define continueCmd 83
  74522. æC 
  74523.  
  74524. æKY doubleBufferCmd
  74525. æFc Sound.h
  74526. æT #define
  74527. æD #define doubleBufferCmd 84
  74528. æC 
  74529.  
  74530. æKY getRateCmd
  74531. æFc Sound.h
  74532. æT #define
  74533. æD #define getRateCmd 85
  74534. æC 
  74535.  
  74536. æKY sizeCmd
  74537. æFc Sound.h
  74538. æT #define
  74539. æD #define sizeCmd 90
  74540. æC 
  74541.  
  74542. æKY convertCmd
  74543. æFc Sound.h
  74544. æT #define
  74545. æD #define convertCmd 91
  74546. æC 
  74547.  
  74548. æKY waveInitChannelMask
  74549. æFc Sound.h
  74550. æT #define
  74551. æD #define waveInitChannelMask 0x07
  74552. æC 
  74553.  
  74554. æKY waveInitChannel0
  74555. æFc Sound.h
  74556. æT #define
  74557. æD #define waveInitChannel0 0x04
  74558. æC 
  74559.  
  74560. æKY waveInitChannel1
  74561. æFc Sound.h
  74562. æT #define
  74563. æD #define waveInitChannel1 0x05
  74564. æC 
  74565.  
  74566. æKY waveInitChannel2
  74567. æFc Sound.h
  74568. æT #define
  74569. æD #define waveInitChannel2 0x06
  74570. æC 
  74571.  
  74572. æKY waveInitChannel3
  74573. æFc Sound.h
  74574. æT #define
  74575. æD #define waveInitChannel3 0x07
  74576. æC 
  74577.  
  74578. æKY dataPointerFlag
  74579. æFc Sound.h
  74580. æT #define
  74581. æD #define dataPointerFlag 0x8000
  74582. æC 
  74583.  
  74584. æKY initSRateMask
  74585. æFc Sound.h
  74586. æT #define
  74587. æD #define initSRateMask 0x0030
  74588. æC 
  74589.  
  74590. æKY initStereoMask
  74591. æFc Sound.h
  74592. æT #define
  74593. æD #define initStereoMask 0x00C0
  74594. æC 
  74595.  
  74596. æKY initChanLeft
  74597. æFc Sound.h
  74598. æT #define
  74599. æD #define initChanLeft 0x0002 /*left stereo channel */
  74600. æC 
  74601.  
  74602. æKY initChanRight
  74603. æFc Sound.h
  74604. æT #define
  74605. æD #define initChanRight 0x0003 /*right stereo channel*/
  74606. æC 
  74607.  
  74608. æKY initSRate22k
  74609. æFc Sound.h
  74610. æT #define
  74611. æD #define initSRate22k 0x0020 /*22k sampling rate*/
  74612. æC 
  74613.  
  74614. æKY initSRate44k
  74615. æFc Sound.h
  74616. æT #define
  74617. æD #define initSRate44k 0x0030 /*44k sampling rate*/
  74618. æC 
  74619.  
  74620. æKY initMono
  74621. æFc Sound.h
  74622. æT #define
  74623. æD #define initMono 0x0080 /*monophonic channel*/
  74624. æC 
  74625.  
  74626. æKY initStereo
  74627. æFc Sound.h
  74628. æT #define
  74629. æD #define initStereo 0x00C0 /*stereo channel*/
  74630. æC 
  74631.  
  74632. æKY initNoLERP
  74633. æFc Sound.h
  74634. æT #define
  74635. æD #define initNoLERP 0x0004 /*no Linear Interpolation with the SR Convert*/
  74636. æC 
  74637.  
  74638. æKY initNoSRConv
  74639. æFc Sound.h
  74640. æT #define
  74641. æD #define initNoSRConv 0x0008
  74642. æC 
  74643.  
  74644. æKY initMACE3
  74645. æFc Sound.h
  74646. æT #define
  74647. æD #define initMACE3 0x0300
  74648. æC 
  74649.  
  74650. æKY initMACE6
  74651. æFc Sound.h
  74652. æT #define
  74653. æD #define initMACE6 0x0400
  74654. æC 
  74655.  
  74656. æKY midiDataCmd
  74657. æFc Sound.h
  74658. æT #define
  74659. æD 
  74660. /*  Init bits for 4-voice synth ONLY */
  74661.  
  74662. #define midiDataCmd 100
  74663. æC 
  74664.  
  74665. æKY initChan0
  74666. æFc Sound.h
  74667. æT #define
  74668. æD #define initChan0 4 /*channel 0 - wave table only*/
  74669. æC 
  74670.  
  74671. æKY initChan1
  74672. æFc Sound.h
  74673. æT #define
  74674. æD #define initChan1 5 /*channel 1 - wave table only*/
  74675. æC 
  74676.  
  74677. æKY initChan2
  74678. æFc Sound.h
  74679. æT #define
  74680. æD #define initChan2 6 /*channel 2 - wave table only*/
  74681. æC 
  74682.  
  74683. æKY initChan3
  74684. æFc Sound.h
  74685. æT #define
  74686. æD #define initChan3 7 /*channel 3 - wave table only*/
  74687. æC 
  74688.  
  74689. æKY stdSH
  74690. æFc Sound.h
  74691. æT #define
  74692. æD #define stdSH 0x00
  74693. æC 
  74694.  
  74695. æKY extSH
  74696. æFc Sound.h
  74697. æT #define
  74698. æD #define extSH 0xFF
  74699. æC 
  74700.  
  74701. æKY cmpSH
  74702. æFc Sound.h
  74703. æT #define
  74704. æD #define cmpSH 0xFE
  74705. æC 
  74706.  
  74707. æKY notCompressed
  74708. æFc Sound.h
  74709. æT #define
  74710. æD #define notCompressed 0
  74711. æC 
  74712.  
  74713. æKY twoToOne
  74714. æFc Sound.h
  74715. æT #define
  74716. æD #define twoToOne 1
  74717. æC 
  74718.  
  74719. æKY eightToThree
  74720. æFc Sound.h
  74721. æT #define
  74722. æD #define eightToThree 2
  74723. æC 
  74724.  
  74725. æKY threeToOne
  74726. æFc Sound.h
  74727. æT #define
  74728. æD #define threeToOne 3
  74729. æC 
  74730.  
  74731. æKY sixToOne
  74732. æFc Sound.h
  74733. æT #define
  74734. æD #define sixToOne 4
  74735. æC 
  74736.  
  74737. æKY outsideCmpSH
  74738. æFc Sound.h
  74739. æT #define
  74740. æD #define outsideCmpSH 0
  74741. æC 
  74742.  
  74743. æKY insideCmpSH
  74744. æFc Sound.h
  74745. æT #define
  74746. æD #define insideCmpSH 1
  74747. æC 
  74748.  
  74749. æKY ACESuccess
  74750. æFc Sound.h
  74751. æT #define
  74752. æD #define ACESuccess 0
  74753. æC 
  74754.  
  74755. æKY ACEMemFull
  74756. æFc Sound.h
  74757. æT #define
  74758. æD #define ACEMemFull 1
  74759. æC 
  74760.  
  74761. æKY ACENilBlock
  74762. æFc Sound.h
  74763. æT #define
  74764. æD #define ACENilBlock 2
  74765. æC 
  74766.  
  74767. æKY ACEBadComp
  74768. æFc Sound.h
  74769. æT #define
  74770. æD #define ACEBadComp 3
  74771. æC 
  74772.  
  74773. æKY ACEBadEncode
  74774. æFc Sound.h
  74775. æT #define
  74776. æD #define ACEBadEncode 4
  74777. æC 
  74778.  
  74779. æKY ACEBadDest
  74780. æFc Sound.h
  74781. æT #define
  74782. æD #define ACEBadDest 5
  74783. æC 
  74784.  
  74785. æKY ACEBadCmd
  74786. æFc Sound.h
  74787. æT #define
  74788. æD #define ACEBadCmd 6
  74789. æC 
  74790.  
  74791. æKY sixToOnePacketSize
  74792. æFc Sound.h
  74793. æT #define
  74794. æD #define sixToOnePacketSize 8
  74795. æC 
  74796.  
  74797. æKY threeToOnePacketSize
  74798. æFc Sound.h
  74799. æT #define
  74800. æD #define threeToOnePacketSize 16
  74801. æC 
  74802.  
  74803. æKY StateBlockSize
  74804. æFc Sound.h
  74805. æT #define
  74806. æD #define StateBlockSize 64
  74807. æC 
  74808.  
  74809. æKY LeftOverBlockSize
  74810. æFc Sound.h
  74811. æT #define
  74812. æD #define LeftOverBlockSize 32
  74813. æC 
  74814.  
  74815. æKY FirstSoundFormat
  74816. æFc Sound.h
  74817. æT #define
  74818. æD #define FirstSoundFormat 0x0001 /* general sound format */
  74819. æC 
  74820.  
  74821. æKY SecondSoundFormat
  74822. æFc Sound.h
  74823. æT #define
  74824. æD #define SecondSoundFormat 2 /* special sampled sound format */
  74825. æC 
  74826.  
  74827. æKY stdQLength
  74828. æFc Sound.h
  74829. æT #define
  74830. æD #define stdQLength 128
  74831. æC 
  74832.  
  74833. æKY setPtrBit
  74834. æFc Sound.h
  74835. æT #define
  74836. æD #define setPtrBit 0x8000
  74837. æC 
  74838.  
  74839. æKY firstSoundFormat
  74840. æFc Sound.h
  74841. æT #define
  74842. æD #define firstSoundFormat 1 /*first and only version we can deal with*/
  74843. æC 
  74844.  
  74845. æKY sysBeepDisable
  74846. æFc Sound.h
  74847. æT #define
  74848. æD #define sysBeepDisable 0x0000
  74849. æC 
  74850.  
  74851. æKY sysBeepEnable
  74852. æFc Sound.h
  74853. æT #define
  74854. æD #define sysBeepEnable 0x0001
  74855. æC 
  74856.  
  74857. æKY unitTypeNoSelection
  74858. æFc Sound.h
  74859. æT #define
  74860. æD 
  74861. /* unitTypes for AudioSelection.unitType */
  74862.  
  74863. #define unitTypeNoSelection 0xFFFF
  74864. æC 
  74865.  
  74866. æKY unitTypeSeconds
  74867. æFc Sound.h
  74868. æT #define
  74869. æD #define unitTypeSeconds 0x0000
  74870. æC 
  74871.  
  74872. æKY dbBufferEmpty
  74873. æFc Sound.h
  74874. æT #define
  74875. æD 
  74876. /* Constants for SndPlayDoubleBuffer */
  74877.  
  74878. #define dbBufferEmpty 0x00000000
  74879. æC 
  74880.  
  74881. æKY dbBufferEmptyMask
  74882. æFc Sound.h
  74883. æT #define
  74884. æD #define dbBufferEmptyMask 0xFFFFFFFE
  74885. æC 
  74886.  
  74887. æKY dbBufferReady
  74888. æFc Sound.h
  74889. æT #define
  74890. æD #define dbBufferReady 0x00000001
  74891. æC 
  74892.  
  74893. æKY dbBufferExhausted
  74894. æFc Sound.h
  74895. æT #define
  74896. æD #define dbBufferExhausted 0x00000002
  74897. æC 
  74898.  
  74899. æKY dbLastBuffer
  74900. æFc Sound.h
  74901. æT #define
  74902. æD #define dbLastBuffer 0x00000004
  74903. æC 
  74904.  
  74905. æKY MOVEL
  74906. æFc Sound.h
  74907. æT #define
  74908. æD 
  74909. /* ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••*/
  74910. /*
  74911. /*New Enhanced Sound Manager 7.0 Calls
  74912. /*
  74913. /*These will soon be supported by a Glue Library so that all this ugly
  74914. /*stuff will disappear and the traps will look like non-indexed traps.
  74915. /*
  74916. /*•••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• */
  74917.  
  74918. #define MOVEL 0X203C
  74919. æC 
  74920.  
  74921. æKY maceToolNum
  74922. æFc Sound.h
  74923. æT #define
  74924. æD 
  74925. /*  constants for MACE in the dispatcher  */
  74926.  
  74927. #define maceToolNum 16
  74928. æC 
  74929.  
  74930. æKY sMgrMACEVersion
  74931. æFc Sound.h
  74932. æT #define
  74933. æD #define sMgrMACEVersion 0
  74934. æC 
  74935.  
  74936. æKY sMgrComp3to1
  74937. æFc Sound.h
  74938. æT #define
  74939. æD #define sMgrComp3to1 4
  74940. æC 
  74941.  
  74942. æKY sMgrExp1to3
  74943. æFc Sound.h
  74944. æT #define
  74945. æD #define sMgrExp1to3 8
  74946. æC 
  74947.  
  74948. æKY sMgrComp6to1
  74949. æFc Sound.h
  74950. æT #define
  74951. æD #define sMgrComp6to1 12
  74952. æC 
  74953.  
  74954. æKY sMgrExp1to6
  74955. æFc Sound.h
  74956. æT #define
  74957. æD #define sMgrExp1to6 16
  74958. æC 
  74959.  
  74960. æKY sMgrToolNum
  74961. æFc Sound.h
  74962. æT #define
  74963. æD 
  74964. /* constants for Sound Manager Extensions in the dispatcher */
  74965.  
  74966. #define sMgrToolNum 8
  74967. æC 
  74968.  
  74969. æKY sMgrSndSoundManagerVersion
  74970. æFc Sound.h
  74971. æT #define
  74972. æD #define sMgrSndSoundManagerVersion 0
  74973. æC 
  74974.  
  74975. æKY sMgrSndStartFilePlay
  74976. æFc Sound.h
  74977. æT #define
  74978. æD #define sMgrSndStartFilePlay 4
  74979. æC 
  74980.  
  74981. æKY sMgrSndPauseFilePlay
  74982. æFc Sound.h
  74983. æT #define
  74984. æD #define sMgrSndPauseFilePlay 8
  74985. æC 
  74986.  
  74987. æKY sMgrSndStopFilePlay
  74988. æFc Sound.h
  74989. æT #define
  74990. æD #define sMgrSndStopFilePlay 12
  74991. æC 
  74992.  
  74993. æKY sMgrSndChannelStatus
  74994. æFc Sound.h
  74995. æT #define
  74996. æD #define sMgrSndChannelStatus 16
  74997. æC 
  74998.  
  74999. æKY sMgrSndManagerStatus
  75000. æFc Sound.h
  75001. æT #define
  75002. æD #define sMgrSndManagerStatus 20
  75003. æC 
  75004.  
  75005. æKY sMgrSndGetSysBeepState
  75006. æFc Sound.h
  75007. æT #define
  75008. æD #define sMgrSndGetSysBeepState 24
  75009. æC 
  75010.  
  75011. æKY sMgrSndSetSysBeepState
  75012. æFc Sound.h
  75013. æT #define
  75014. æD #define sMgrSndSetSysBeepState 28
  75015. æC 
  75016.  
  75017. æKY sMgrSndPlayDoubleBuffer
  75018. æFc Sound.h
  75019. æT #define
  75020. æD #define sMgrSndPlayDoubleBuffer 32
  75021. æC 
  75022.  
  75023. æKY sMgrSndGetBufferStufferLoad
  75024. æFc Sound.h
  75025. æT #define
  75026. æD #define sMgrSndGetBufferStufferLoad 36
  75027. æC 
  75028.  
  75029. æKY sMgrSndGetMixerLoad
  75030. æFc Sound.h
  75031. æT #define
  75032. æD #define sMgrSndGetMixerLoad 40
  75033. æC 
  75034.  
  75035. æKY FreeWave[30001]
  75036. æFc Sound.h
  75037. æT typedef
  75038. æD typedef unsigned char FreeWave[30001];
  75039. æC 
  75040.  
  75041. æKY Time
  75042. æFc Sound.h
  75043. æT typedef
  75044. æD typedef long Time;  /* in half milliseconds */
  75045. æC 
  75046.  
  75047. æKY Wave
  75048. æFc Sound.h
  75049. æT typedef
  75050. æD typedef unsigned char Wave[256];
  75051. typedef Wave *WavePtr;
  75052. æC 
  75053. »Four-Tone Synthesizer
  75054.  
  75055. The four-tone synthesizer is used to produce harmonic sounds such as music. It can
  75056. simultaneously generate four different sounds, each with its own frequency, phase,
  75057. and waveform.
  75058.  
  75059. A four-tone synthesizer buffer has the following structure:
  75060.  
  75061. TYPE  FTSynthRec = RECORD
  75062.                      mode:    INTEGER;     {always ftMode}
  75063.                      sndRec:  FTSndRecPtr  {tones to play}
  75064.                    END;
  75065.  
  75066.       FTSynthPtr = ^FTSynthRec;
  75067.  
  75068. The sndRec field points to a four-tone record, which describes the four tones:
  75069.  
  75070. TYPE  FTSoundRec =  RECORD
  75071.                       duration:     INTEGER;  {duration in ticks}
  75072.                       sound1Rate:   Fixed;    {tone 1 cycle rate}
  75073.                       sound1Phase:  LONGINT;  {tone 1 byte offset}
  75074.                       sound2Rate:   Fixed;    {tone 2 cycle rate}
  75075.                       sound2Phase:  LONGINT;  {tone 2 byte offset}
  75076.                       sound3Rate:   Fixed;    {tone 3 cycle rate}
  75077.                       sound3Phase:  LONGINT;  {tone 3 byte offset}
  75078.                       sound4Rate:   Fixed;    {tone 4 cycle rate}
  75079.                       sound4Phase:  LONGINT;  {tone 4 byte offset}
  75080.                       sound1Wave:   WavePtr;  {tone 1 waveform}
  75081.                       sound2Wave:   WavePtr;  {tone 2 waveform}
  75082.                       sound3Wave:   WavePtr;  {tone 3 waveform}
  75083.                       sound4Wave:   WavePtr   {tone 4 waveform}
  75084.                     END;
  75085.  
  75086.       FTSndRecPtr = ^FTSoundRec:
  75087.       Wave        = PACKED ARRAY[0..255] OF Byte;
  75088.       WavePtr     = ^Wave;
  75089.  
  75090. Assembly-language note:  The address of the four-tone record currently in use
  75091.                          is stored in the global variable SoundPtr.
  75092.  
  75093. The duration integer indicates the number of ticks that the sound will be generated.
  75094. Each phase long integer indicates the byte within the waveform description at which
  75095. the synthesizer should begin producing sound (the first byte is byte number 0). Each
  75096. rate value determines the speed at which the synthesizer cycles through the waveform,
  75097. from 0 to 255.
  75098.  
  75099. The four-tone synthesizer creates sound by starting at the byte in the waveform
  75100. description specified by the phase, and skipping ahead the number of bytes specified
  75101. by the rate field every 44.93 microseconds; when the time specified by the duration
  75102. has elapsed, the synthesizer stops. The rate field determines how the waveform will
  75103. be “sampled”, as shown in Figure 4. For nonperiodic waveforms, this is best illustrated
  75104. by example:  If the rate field is 1, each byte value in the waveform will be used,
  75105. each producing sound for 44.93 microseconds. If the rate field is 0.1, each byte will
  75106. be used 10 times, each therefore producing sound for a total of 449.3 microseconds.
  75107. If the rate field is 5, only every fifth byte in the waveform will be sampled, each
  75108. producing sound for 44.93 microseconds.
  75109.  
  75110. If the waveform contains one wavelength, the frequency that the rate corresponds to
  75111. is given by:
  75112.  
  75113.   frequency (Hz) = 1000000 / (44.93 / (rate/256))
  75114.  
  75115. You can use the Toolbox Utility routines FixMul and FixRatio to calculate this, as
  75116. follows:
  75117.  
  75118.   frequency := FixMul(rate,FixRatio(22257,256))
  75119.  
  75120. The maximum rate of 256 corresponds to approximately 22.3 kilohertz if the waveform
  75121. contains one wavelength, and a rate of 0 produces no sound. A partial list of rate
  75122. values and corresponding frequencies for notes is given in the summary at the end of
  75123. this chapter.
  75124.  
  75125. æKY FFSynthRec
  75126. FFSynthPtr
  75127. æFc Sound.h
  75128. æT struct
  75129. æD struct FFSynthRec {
  75130.     short mode;
  75131.     Fixed count;
  75132.     FreeWave waveBytes;
  75133. };
  75134.  
  75135. typedef struct FFSynthRec FFSynthRec;
  75136. typedef FFSynthRec *FFSynthPtr;
  75137.  
  75138. æC 
  75139. »Free-Form Synthesizer
  75140.  
  75141. The free-form synthesizer is used to synthesize complex music and speech. The sound
  75142. to be produced is represented as a waveform whose complexity and length are limited
  75143. only by available memory.
  75144.  
  75145. A free-form synthesizer buffer has the following structure:
  75146.  
  75147. TYPE  FFSynthRec = RECORD
  75148.                      mode:       INTEGER;  {always ffMode}
  75149.                      count:      Fixed;    {“sampling” factor}
  75150.                      waveBytes:  FreeWave  {waveform description}
  75151.                    END;
  75152.  
  75153.       FFSynthPtr = ^FFSynthRec;
  75154.       FreeWave   = PACKED ARRAY[0..30000] OF Byte;
  75155.  
  75156. The type FreeWave is declared with 30001 elements to allow you to pass a very long
  75157. waveform. To be space-efficient, your application shouldn’t declare a variable of
  75158. type FreeWave; instead, you can do something like this:
  75159.  
  75160.   VAR  myPtr:  Ptr;
  75161.        myHandle:  Handle;
  75162.        myFFPtr:  FFSynthPtr;
  75163.        . . .
  75164.   myHandle := NewHandle(buffSize);  {allocate space for the buffer}
  75165.   HLock(myHandle);                  {lock the buffer}
  75166.   myPtr := myHandle^;               {dereference the handle}
  75167.   myFFPtr := FFSynthPtr(myPtr);     {coerce type to FFSynthPtr}
  75168.   myFFPtr^.mode := ffMode;          {identify the synthesizer}
  75169.   myFFPtr^.count := FixRatio(1,1);  {fill the buffer with values }
  75170.   myFFPtr^.waveBytes[0] := 0;       { describing the sound}
  75171.   . . .
  75172.   StartSound(myPtr,buffSize,POINTER(–1));  {produce the sound}
  75173.   HUnlock(myHandle)                        {unlock the buffer}
  75174.  
  75175. where buffSize contains the number of bytes in the synthesizer buffer. This example
  75176. dereferences handles instead of using pointers directly, to minimize the number of
  75177. nonrelocatable objects in the heap.
  75178.  
  75179. •••Refer to Figure 4.•••
  75180.  
  75181. Figure 4–Effect of the Rate Field
  75182.  
  75183. The free-form synthesizer creates sound by starting at the first byte in the waveform
  75184. and skipping ahead the number of bytes specified by count every 44.93 microseconds.
  75185. The count field determines how the waveform will be “sampled”;
  75186. it’s analogous to the rate field of the four-tone synthesizer (see Figure 4 above).
  75187. When the end of the waveform is reached, the synthesizer will stop.
  75188.  
  75189. For periodic waveforms, you can determine the frequency of the wave cycle by using
  75190. the following relationship:
  75191.  
  75192.   frequency (Hz) = 1000000 / (44.93 * (wavelength/count))
  75193.  
  75194. You can calculate this with Toolbox Utility routines as follows:
  75195.  
  75196.   frequency := FixMul(count,FixRatio(22257,wavelength))
  75197.  
  75198. The wavelength is given in bytes. For example, the frequency of a wave with a 100-byte
  75199. wavelength played at a count value of 2 would be approximately 445 Hz.
  75200.  
  75201. æKY Tone
  75202. æFc Sound.h
  75203. æT struct
  75204. æD struct Tone {
  75205.     short count;
  75206.     short amplitude;
  75207.     short duration;
  75208. };
  75209.  
  75210. typedef struct Tone Tone;
  75211. typedef Tone Tones[5001];
  75212.  
  75213. æC 
  75214.  
  75215. æKY SWSynthRec
  75216. SWSynthPtr
  75217. æFc Sound.h
  75218. æT struct
  75219. æD struct SWSynthRec {
  75220.     short mode;
  75221.     Tones triplets;
  75222. };
  75223.  
  75224. typedef struct SWSynthRec SWSynthRec;
  75225. typedef SWSynthRec *SWSynthPtr;
  75226.  
  75227. æC 
  75228. »Square-Wave Synthesizer
  75229.  
  75230. The square-wave synthesizer is used to make sounds such as beeps. A square-wave
  75231. synthesizer buffer has the following structure:
  75232.  
  75233. TYPE  SWSynthRec = RECORD
  75234.                      mode:      INTEGER;  {always swMode}
  75235.                      triplets:  Tones     {sounds}
  75236.                    END;
  75237.  
  75238.       SWSynthPtr = ^SWSynthRec;
  75239.       Tones      = ARRAY[0..5000] OF Tone;
  75240.       Tone       = RECORD
  75241.                      count:      INTEGER;   {frequency}
  75242.                      amplitude:  INTEGER;   {amplitude, 0-255}
  75243.                      duration:   INTEGER    {duration in ticks}
  75244.                    END;
  75245.  
  75246. Each tone triplet contains the count, amplitude, and duration of a different sound.
  75247. You can store as many triplets in a synthesizer buffer as there’s room for.
  75248.  
  75249. The count integer can range in value from 0 to 65535. The actual frequency the count
  75250. corresponds to is given by the relationship:
  75251.  
  75252.   frequency (Hz) = 783360 / count
  75253.  
  75254. A partial list of count values and corresponding frequencies for notes is given in
  75255. the summary at the end of this chapter.
  75256.  
  75257. The type Tones is declared with 5001 elements to allow you to pass up to 5000 sounds
  75258. (the last element must contain 0). To be space-efficient, your application shouldn’t
  75259. declare a variable of type Tones; instead, you can do something like this:
  75260.  
  75261.   VAR myPtr:    Ptr;
  75262.       myHandle: Handle;
  75263.       mySWPtr:  SWSynthPtr;
  75264.       . . .
  75265.   myHandle := NewHandle(buffSize);         {allocate space for the buffer}
  75266.   HLock(myHandle);                         {lock the buffer}
  75267.   myPtr := myHandle^;                      {dereference the handle}
  75268.   mySWPtr := SWSynthPtr(myPtr);            {coerce type to SWSynthPtr}
  75269.   mySWPtr^.mode := swMode;                 {identify the synthesizer}
  75270.   mySWPtr^.triplets[0].count := 2;         {fill the buffer with values }
  75271.   . . .                                    { describing the sound}
  75272.   StartSound(myPtr,buffSize,POINTER(-1));  {produce the sound}
  75273.   HUnlock(myHandle)                        {unlock the buffer}
  75274.  
  75275. where buffSize contains the number of bytes in the synthesizer buffer. This example
  75276. dereferences handles instead of using pointers directly, to minimize the number of
  75277. nonrelocatable objects in the heap.
  75278.  
  75279. Assembly-language note:  The global variable CurPitch contains the current
  75280.                          value of the count field.
  75281.  
  75282. The amplitude can range from 0 to 255. The duration specifies the number of ticks
  75283. that the sound will be generated.
  75284.  
  75285. The list of tones ends with a triplet in which all fields are set to 0. When the
  75286. square-wave synthesizer is used, the sound specified by each triplet is generated
  75287. once, and then the synthesizer stops.
  75288.  
  75289. æKY FTSoundRec
  75290. FTSndRecPtr
  75291. æFc Sound.h
  75292. æT struct
  75293. æD struct FTSoundRec {
  75294.     short duration;
  75295.     Fixed sound1Rate;
  75296.     long sound1Phase;
  75297.     Fixed sound2Rate;
  75298.     long sound2Phase;
  75299.     Fixed sound3Rate;
  75300.     long sound3Phase;
  75301.     Fixed sound4Rate;
  75302.     long sound4Phase;
  75303.     WavePtr sound1Wave;
  75304.     WavePtr sound2Wave;
  75305.     WavePtr sound3Wave;
  75306.     WavePtr sound4Wave;
  75307. };
  75308.  
  75309. typedef struct FTSoundRec FTSoundRec;
  75310. typedef FTSoundRec *FTSndRecPtr;
  75311.  
  75312. æC 
  75313. »Four-Tone Synthesizer
  75314.  
  75315. The four-tone synthesizer is used to produce harmonic sounds such as music. It can
  75316. simultaneously generate four different sounds, each with its own frequency, phase,
  75317. and waveform.
  75318.  
  75319. A four-tone synthesizer buffer has the following structure:
  75320.  
  75321. TYPE  FTSynthRec = RECORD
  75322.                      mode:    INTEGER;     {always ftMode}
  75323.                      sndRec:  FTSndRecPtr  {tones to play}
  75324.                    END;
  75325.  
  75326.       FTSynthPtr = ^FTSynthRec;
  75327.  
  75328. The sndRec field points to a four-tone record, which describes the four tones:
  75329.  
  75330. TYPE  FTSoundRec =  RECORD
  75331.                       duration:     INTEGER;  {duration in ticks}
  75332.                       sound1Rate:   Fixed;    {tone 1 cycle rate}
  75333.                       sound1Phase:  LONGINT;  {tone 1 byte offset}
  75334.                       sound2Rate:   Fixed;    {tone 2 cycle rate}
  75335.                       sound2Phase:  LONGINT;  {tone 2 byte offset}
  75336.                       sound3Rate:   Fixed;    {tone 3 cycle rate}
  75337.                       sound3Phase:  LONGINT;  {tone 3 byte offset}
  75338.                       sound4Rate:   Fixed;    {tone 4 cycle rate}
  75339.                       sound4Phase:  LONGINT;  {tone 4 byte offset}
  75340.                       sound1Wave:   WavePtr;  {tone 1 waveform}
  75341.                       sound2Wave:   WavePtr;  {tone 2 waveform}
  75342.                       sound3Wave:   WavePtr;  {tone 3 waveform}
  75343.                       sound4Wave:   WavePtr   {tone 4 waveform}
  75344.                     END;
  75345.  
  75346.       FTSndRecPtr = ^FTSoundRec:
  75347.       Wave        = PACKED ARRAY[0..255] OF Byte;
  75348.       WavePtr     = ^Wave;
  75349.  
  75350. Assembly-language note:  The address of the four-tone record currently in use
  75351.                          is stored in the global variable SoundPtr.
  75352.  
  75353. The duration integer indicates the number of ticks that the sound will be generated.
  75354. Each phase long integer indicates the byte within the waveform description at which
  75355. the synthesizer should begin producing sound (the first byte is byte number 0). Each
  75356. rate value determines the speed at which the synthesizer cycles through the waveform,
  75357. from 0 to 255.
  75358.  
  75359. The four-tone synthesizer creates sound by starting at the byte in the waveform
  75360. description specified by the phase, and skipping ahead the number of bytes specified
  75361. by the rate field every 44.93 microseconds; when the time specified by the duration
  75362. has elapsed, the synthesizer stops. The rate field determines how the waveform will
  75363. be “sampled”, as shown in Figure 4. For nonperiodic waveforms, this is best illustrated
  75364. by example:  If the rate field is 1, each byte value in the waveform will be used,
  75365. each producing sound for 44.93 microseconds. If the rate field is 0.1, each byte will
  75366. be used 10 times, each therefore producing sound for a total of 449.3 microseconds.
  75367. If the rate field is 5, only every fifth byte in the waveform will be sampled, each
  75368. producing sound for 44.93 microseconds.
  75369.  
  75370. If the waveform contains one wavelength, the frequency that the rate corresponds to
  75371. is given by:
  75372.  
  75373.   frequency (Hz) = 1000000 / (44.93 / (rate/256))
  75374.  
  75375. You can use the Toolbox Utility routines FixMul and FixRatio to calculate this, as
  75376. follows:
  75377.  
  75378.   frequency := FixMul(rate,FixRatio(22257,256))
  75379.  
  75380. The maximum rate of 256 corresponds to approximately 22.3 kilohertz if the waveform
  75381. contains one wavelength, and a rate of 0 produces no sound. A partial list of rate
  75382. values and corresponding frequencies for notes is given in the summary at the end of
  75383. this chapter.
  75384.  
  75385. æKY FTSynthRec
  75386. FTSynthPtr
  75387. æFc Sound.h
  75388. æT struct
  75389. æD struct FTSynthRec {
  75390.     short mode;
  75391.     FTSndRecPtr sndRec;
  75392. };
  75393.  
  75394. typedef struct FTSynthRec FTSynthRec;
  75395. typedef FTSynthRec *FTSynthPtr;
  75396.  
  75397. æC 
  75398. »Four-Tone Synthesizer
  75399.  
  75400. The four-tone synthesizer is used to produce harmonic sounds such as music. It can
  75401. simultaneously generate four different sounds, each with its own frequency, phase,
  75402. and waveform.
  75403.  
  75404. A four-tone synthesizer buffer has the following structure:
  75405.  
  75406. TYPE  FTSynthRec = RECORD
  75407.                      mode:    INTEGER;     {always ftMode}
  75408.                      sndRec:  FTSndRecPtr  {tones to play}
  75409.                    END;
  75410.  
  75411.       FTSynthPtr = ^FTSynthRec;
  75412.  
  75413. The sndRec field points to a four-tone record, which describes the four tones:
  75414.  
  75415. TYPE  FTSoundRec =  RECORD
  75416.                       duration:     INTEGER;  {duration in ticks}
  75417.                       sound1Rate:   Fixed;    {tone 1 cycle rate}
  75418.                       sound1Phase:  LONGINT;  {tone 1 byte offset}
  75419.                       sound2Rate:   Fixed;    {tone 2 cycle rate}
  75420.                       sound2Phase:  LONGINT;  {tone 2 byte offset}
  75421.                       sound3Rate:   Fixed;    {tone 3 cycle rate}
  75422.                       sound3Phase:  LONGINT;  {tone 3 byte offset}
  75423.                       sound4Rate:   Fixed;    {tone 4 cycle rate}
  75424.                       sound4Phase:  LONGINT;  {tone 4 byte offset}
  75425.                       sound1Wave:   WavePtr;  {tone 1 waveform}
  75426.                       sound2Wave:   WavePtr;  {tone 2 waveform}
  75427.                       sound3Wave:   WavePtr;  {tone 3 waveform}
  75428.                       sound4Wave:   WavePtr   {tone 4 waveform}
  75429.                     END;
  75430.  
  75431.       FTSndRecPtr = ^FTSoundRec:
  75432.       Wave        = PACKED ARRAY[0..255] OF Byte;
  75433.       WavePtr     = ^Wave;
  75434.  
  75435. Assembly-language note:  The address of the four-tone record currently in use
  75436.                          is stored in the global variable SoundPtr.
  75437.  
  75438. The duration integer indicates the number of ticks that the sound will be generated.
  75439. Each phase long integer indicates the byte within the waveform description at which
  75440. the synthesizer should begin producing sound (the first byte is byte number 0). Each
  75441. rate value determines the speed at which the synthesizer cycles through the waveform,
  75442. from 0 to 255.
  75443.  
  75444. The four-tone synthesizer creates sound by starting at the byte in the waveform
  75445. description specified by the phase, and skipping ahead the number of bytes specified
  75446. by the rate field every 44.93 microseconds; when the time specified by the duration
  75447. has elapsed, the synthesizer stops. The rate field determines how the waveform will
  75448. be “sampled”, as shown in Figure 4. For nonperiodic waveforms, this is best illustrated
  75449. by example:  If the rate field is 1, each byte value in the waveform will be used,
  75450. each producing sound for 44.93 microseconds. If the rate field is 0.1, each byte will
  75451. be used 10 times, each therefore producing sound for a total of 449.3 microseconds.
  75452. If the rate field is 5, only every fifth byte in the waveform will be sampled, each
  75453. producing sound for 44.93 microseconds.
  75454.  
  75455. If the waveform contains one wavelength, the frequency that the rate corresponds to
  75456. is given by:
  75457.  
  75458.   frequency (Hz) = 1000000 / (44.93 / (rate/256))
  75459.  
  75460. You can use the Toolbox Utility routines FixMul and FixRatio to calculate this, as
  75461. follows:
  75462.  
  75463.   frequency := FixMul(rate,FixRatio(22257,256))
  75464.  
  75465. The maximum rate of 256 corresponds to approximately 22.3 kilohertz if the waveform
  75466. contains one wavelength, and a rate of 0 produces no sound. A partial list of rate
  75467. values and corresponding frequencies for notes is given in the summary at the end of
  75468. this chapter.
  75469.  
  75470. æKY SndCommand
  75471. æFc Sound.h
  75472. æT struct
  75473. æD struct SndCommand {
  75474.     unsigned short cmd;
  75475.     short param1;
  75476.     long param2;
  75477. };
  75478.  
  75479. typedef struct SndCommand SndCommand;
  75480. typedef struct ModifierStub *ModifierStubPtr;
  75481. typedef struct SndChannel *SndChannelPtr;
  75482.  
  75483. typedef pascal void (*SndCompletionProcPtr)(void);
  75484. typedef pascal Boolean (*SndModifierProcPtr)(SndChannelPtr chan, SndCommand *cmd, ModifierStubPtr mod);
  75485. typedef pascal Boolean (*SndCallBackProcPtr)(SndChannelPtr chan, SndCommand cmd);
  75486.  
  75487.  
  75488. æC 
  75489.  
  75490. æKY SndChannel
  75491. æFc Sound.h
  75492. æT struct
  75493. æD struct SndChannel {
  75494.     struct SndChannel *nextChan;
  75495.     ModifierStubPtr firstMod;
  75496.     SndCallBackProcPtr callBack;
  75497.     long userInfo;
  75498.     Time wait; /*The following is for internal Sound Manager use only.*/
  75499.     SndCommand cmdInProgress;
  75500.     short flags;
  75501.     short qLength;
  75502.     short qHead; /*next spot to read or -1 if empty*/
  75503.     short qTail; /*next spot to write = qHead if full*/
  75504.     SndCommand queue[128];
  75505. };
  75506.  
  75507. typedef struct SndChannel SndChannel;
  75508. æC 
  75509.  
  75510. æKY ModifierStub
  75511. æFc Sound.h
  75512. æT struct
  75513. æD struct ModifierStub {
  75514.     struct ModifierStub *nextStub;
  75515.     SndModifierProcPtr code;
  75516.     long userInfo;
  75517.     Time count;
  75518.     Time every;
  75519.     char flags;
  75520.     char hState;
  75521. };
  75522.  
  75523. typedef struct ModifierStub ModifierStub;
  75524. æC 
  75525. »FUNCTION Modifier(chan: SndChannelPtr; VAR cmd: SndCommand;
  75526.                   mod: ModifierStubPtr) : BOOLEAN
  75527.  
  75528. A modifier will be called when the command reaches the end of the queue, before being
  75529. sent to the synthesizer or other modifiers that may be installed.  Chan will contain
  75530. the channel pointer allowing multiple wave table channels to be supported by the same
  75531. modifier.  The ModifierStub is a record created by the Sound Manager during the call
  75532. _SndAddModifier.  A pointer to the ModifierStub is in mod.  There are two special
  75533. commands that the modifier must support, the initCmd and the freeCmd.
  75534.  
  75535. Warning:  Refer to the section “Current Sound Manager” regarding modifiers
  75536.           being saved as resources.
  75537.  
  75538.   ModifierStub = PACKED RECORD
  75539.                    nextStub:    ModifierStubPtr;  {pointer to next stub}
  75540.                    code:        ProcPtr;          {pointer to modifier}
  75541.                    userInfo:    LONGINT;          {free for modifier’s use}
  75542.                    count:       Time;             {used internally}
  75543.                    every:       Time;             {used internally}
  75544.                    flags:       SignedByte;       {used internally}
  75545.                    hState:      SignedByte;       {used internally}
  75546.                  END;
  75547.  
  75548. The initCmd is sent by the Sound Manager when an application calls
  75549. _SndAddModifier.  This is a command telling the modifier to allocate any additional
  75550. data.  The ModiferStub contains a four byte field, userInfo, that can be used as a
  75551. pointer to this additional memory.  The initCmd will not be sent to a modifier at
  75552. interrupt time.  This allows a modifier to allocate memory and save the current
  75553. application’s A5.   All memory storage allocated by the modifier must be locked,
  75554. since the modifier will be called at interrupt time.
  75555.  
  75556. The freeCmd will be sent to the modifier when the Sound Manager is disposing of the
  75557. channel.  This command will not be sent at interrupt time.  At this point the modifier
  75558. should free any data it may have allocated.
  75559.  
  75560. A modifier will be given the current command, before the command is sent to the
  75561. synthesizer or other modifiers.  The current command is sent to the modifier in the
  75562. variable cmd.  A nullCmd is never sent to a modifier.  If the modifier wished to
  75563. ignore the current command and allow it to be sent on, it would return FALSE.  To
  75564. remove the current command, replace it with a nullCmd and then return FALSE.  To
  75565. alter the current command, replace it with the new one and return FALSE.  Returning
  75566. FALSE means that the modifier has completed its function.
  75567.  
  75568. If the modifier is to send additional commands to the channel, the function will
  75569. return TRUE and may or may not change the current command.  The Sound Manager will
  75570. call the modifier again sending it a requestNextCmd.  The modifier can then replace
  75571. this command with the one desired.  The modifier can continue to return TRUE to send
  75572. additional commands.  The requestNextCmd will indicate the number of times this
  75573. command has been consecutively sent to the modifier.
  75574.  
  75575. Note:  Modifiers are short routines used to perform real-time modifications on
  75576.        channels.  Having too many modifiers, or a lengthy one, may degrade
  75577.        performance.
  75578.  
  75579. æKY SoundHeader
  75580. SoundHeaderPtr
  75581. æFc Sound.h
  75582. æT struct
  75583. æD struct SoundHeader {
  75584.     Ptr samplePtr; /*if NIL then samples are in sampleArea*/
  75585.     unsigned long length;
  75586.     Fixed sampleRate;
  75587.     unsigned long loopStart;
  75588.     unsigned long loopEnd;
  75589.     short baseNote;
  75590.     char sampleArea[1];
  75591. };
  75592.  
  75593. typedef struct SoundHeader SoundHeader;
  75594. typedef SoundHeader *SoundHeaderPtr;
  75595.  
  75596. /* ______________________ structs for Sound Manager____________________________  */
  75597. æC 
  75598.  
  75599. æKY StateBlock
  75600. StateBlockPtr
  75601. æFc Sound.h
  75602. æT struct
  75603. æD struct StateBlock {
  75604.     short stateVar[StateBlockSize];
  75605. };
  75606.  
  75607. typedef struct StateBlock StateBlock;
  75608. typedef StateBlock *StateBlockPtr;
  75609.  
  75610. /* ______________________ structs for ACE____________________________  */
  75611. æC 
  75612.  
  75613. æKY LeftOverBlock
  75614. LeftOverBlockPtr
  75615. æFc Sound.h
  75616. æT struct
  75617. æD struct LeftOverBlock {
  75618.     unsigned long count;
  75619.     char sampleArea[LeftOverBlockSize];
  75620. };
  75621.  
  75622. typedef struct LeftOverBlock LeftOverBlock;
  75623. typedef LeftOverBlock *LeftOverBlockPtr;
  75624.  
  75625. æC 
  75626.  
  75627. æKY CmpSoundHeader
  75628. CmpSoundHeaderPtr
  75629. æFc Sound.h
  75630. æT struct
  75631. æD struct CmpSoundHeader {
  75632.     char *samplePtr; /* CAFF, number of channels  mono = 1*/
  75633.     unsigned long numChannels; /* CAFF, number of channels  mono = 1*/
  75634.     Fixed sampleRate; /* sample rate in Apples Fixed point representation*/
  75635.     unsigned long loopStart; /* loopStart of sound before compression*/
  75636.     unsigned long loopEnd; /* loopEnd of sound before compression*/
  75637.     unsigned char encode; /* data structure used ,  stdSH, extSH, or cmpSH*/
  75638.     unsigned char baseNote; /* same meaning as regular SoundHeader*/
  75639.     unsigned long numFrames; /* length in frames( packetFrames or sampleFrames ) */
  75640.     extended AIFFSampleRate; /* CAFF, IEEE sample rate */
  75641.     Ptr MarkerChunk; /* CAFF, sync track*/
  75642.     Ptr FutureUse1; /* reserved by Apple*/
  75643.     Ptr FutureUse2; /* reserved by Apple */
  75644.     StateBlockPtr StateVars; /*pointer to State Block */
  75645.     LeftOverBlockPtr LeftOverSamples; /* used to save truncated samples between compressions calls */
  75646.     unsigned short compressionID; /* 0 means no compression, non zero means compressionID*/
  75647.     unsigned short packetSize; /* CAFF, number of bits in compressed sample packet*/
  75648.     unsigned short snthID; /* Resource ID of Sound Manager snth that contains NRT C/E*/
  75649.     unsigned short sampleSize; /* CAFF, number of bits in non-compressed sample */
  75650.     char sampleArea[1]; /* space for when samples follow directly*/
  75651. };
  75652.  
  75653. typedef struct CmpSoundHeader CmpSoundHeader;
  75654. typedef CmpSoundHeader *CmpSoundHeaderPtr;
  75655.  
  75656. æC 
  75657.  
  75658. æKY ExtSoundHeader
  75659. ExtSoundHeaderPtr
  75660. æFc Sound.h
  75661. æT struct
  75662. æD struct ExtSoundHeader {
  75663.     char *samplePtr; /* AIFF, IEEE sample rate */
  75664.     unsigned long numChannels; /* AIFF, number of channels,  ie mono = 1 */
  75665.     Fixed sampleRate; /* sample rate in Apples Fixed point representation*/
  75666.     unsigned long loopStart; /* same meaning as regular SoundHeader*/
  75667.     unsigned long loopEnd; /* same meaning as regular SoundHeader*/
  75668.     unsigned char encode; /* data structure used ,  stdSH, extSH, or cmpSH*/
  75669.     unsigned char baseNote; /* same meaning as regular SoundHeader*/
  75670.     unsigned long numSampleFrames; /* length in total number of frames*/
  75671.     extended AIFFSampleRate; /* AIFF, IEEE sample rate */
  75672.     Ptr MarkerChunk; /* AIFF, sync track*/
  75673.     Ptr InstrumentChunks; /* AIFF, */
  75674.     Ptr AESRecording; /* AIFF, */
  75675.     unsigned short sampleSize; /* AIFF, number of bits in sample*/
  75676.     unsigned short FutureUse1; /* reserved by Apple */
  75677.     unsigned long FutureUse2; /* reserved by Apple */
  75678.     unsigned long FutureUse3; /* reserved by Apple */
  75679.     unsigned long FutureUse4; /* reserved by Apple */
  75680.     char sampleArea[1]; /* space for when samples follow directly */
  75681. };
  75682.  
  75683. typedef struct ExtSoundHeader ExtSoundHeader;
  75684. typedef ExtSoundHeader *ExtSoundHeaderPtr;
  75685.  
  75686. æC 
  75687.  
  75688. æKY SMStatus
  75689. SMStatusPtr
  75690. æFc Sound.h
  75691. æT struct
  75692. æD struct SMStatus {
  75693.     short smMaxCPULoad;
  75694.     short smNumChannels;
  75695.     short smCurCPULoad;
  75696. };
  75697.  
  75698. typedef struct SMStatus SMStatus;
  75699. typedef SMStatus *SMStatusPtr;
  75700.  
  75701. æC 
  75702.  
  75703. æKY SCStatus
  75704. SCStatusPtr
  75705. æFc Sound.h
  75706. æT struct
  75707. æD struct SCStatus {
  75708.     Fixed scStartTime;
  75709.     Fixed scEndTime;
  75710.     Fixed scCurrentTime;
  75711.     Boolean scChannelBusy;
  75712.     Boolean scChannelDisposed;
  75713.     Boolean scChannelPaused;
  75714.     char scUnused;
  75715.     unsigned long scChannelAttributes;
  75716.     long scCPULoad;
  75717. };
  75718.  
  75719. typedef struct SCStatus SCStatus;
  75720. typedef SCStatus *SCStatusPtr;
  75721.  
  75722. æC 
  75723.  
  75724. æKY SndDoubleBuffer
  75725. SndDoubleBufferPtr
  75726. æFc Sound.h
  75727. æT struct
  75728. æD struct SndDoubleBuffer {
  75729.     long dbNumFrames;
  75730.     long dbFlags;
  75731.     long dbUserInfo[2];
  75732.     char dbSoundData[1];
  75733. };
  75734.  
  75735. typedef struct SndDoubleBuffer SndDoubleBuffer;
  75736. typedef SndDoubleBuffer *SndDoubleBufferPtr;
  75737.  
  75738. æC 
  75739.  
  75740. æKY AudioSelection
  75741. AudioSelectionPtr
  75742. æFc Sound.h
  75743. æT struct
  75744. æD struct AudioSelection {
  75745.     long unitType;
  75746.     long start;
  75747.     long end;
  75748. };
  75749.  
  75750. typedef struct AudioSelection AudioSelection;
  75751. typedef AudioSelection *AudioSelectionPtr;
  75752.  
  75753. æC 
  75754.  
  75755. æKY SndDoubleBufferHeader
  75756. SndDoubleBufferHeaderPtr
  75757. æFc Sound.h
  75758. æT struct
  75759. æD struct SndDoubleBufferHeader {
  75760.     short dbhNumChannels;
  75761.     short dbhSampleSize;
  75762.     short dbhCompressionID;
  75763.     short dbhPacketSize;
  75764.     Fixed dbhSampleRate;
  75765.     SndDoubleBufferPtr dbhBufferPtr[2];
  75766.     ProcPtr dbhDoubleBack;
  75767. };
  75768.  
  75769. typedef struct SndDoubleBufferHeader SndDoubleBufferHeader;
  75770. typedef SndDoubleBufferHeader *SndDoubleBufferHeaderPtr;
  75771.  
  75772. æC 
  75773.  
  75774. æKY ModRef
  75775. æFc Sound.h
  75776. æT struct
  75777. æD struct ModRef {
  75778.     unsigned short modNumber;
  75779.     long modInit;
  75780. };
  75781.  
  75782. typedef struct ModRef ModRef;
  75783. æC 
  75784.  
  75785. æKY SndListResource
  75786. SndListPtr
  75787. æFc Sound.h
  75788. æT struct
  75789. æD struct SndListResource {
  75790.     short format;
  75791.     short numModifiers;
  75792.     ModRef modifierPart[1]; /*This is a variable length array*/
  75793.     short numCommands;
  75794.     SndCommand commandPart[1]; /*This is a variable length array*/
  75795.     char dataPart[1]; /*This is a variable length array*/
  75796. };
  75797.  
  75798. typedef struct SndListResource SndListResource;
  75799. typedef SndListResource *SndListPtr;
  75800.  
  75801. æC 
  75802.  
  75803. æKY SndDoCommand
  75804. æFc Sound.h
  75805. æT Function
  75806. æTN A803
  75807. æD pascal OSErr SndDoCommand(SndChannelPtr chan,const SndCommand *cmd,Boolean noWait)
  75808.     = 0xA803; 
  75809. æDT OSErr myVariable = SndDoCommand((SndChannelPtr) chan,(const SndCommand *) cmd,(Boolean) noWait);
  75810. æRI V-479, VI
  75811. æC 
  75812. This routine sends the sound command specified in the cmd parameter to the
  75813. existing channel’s command queue. If the noWait parameter is set to FALSE and
  75814. the queue is full, the Sound Manager waits until there is space to add the
  75815. command. If noWait is set to TRUE and the channel is full, the Sound Manager
  75816. does not send the command and returns the queueFull error.
  75817.  
  75818. Result codes
  75819. noErr          0  No error
  75820. queueFull   –203  No room in the queue
  75821. badChannel  –205  Channel is corrupt or unusable
  75822.  
  75823. æKY SndDoImmediate
  75824. æFc Sound.h
  75825. æT Function
  75826. æTN A804
  75827. æD pascal OSErr SndDoImmediate(SndChannelPtr chan,const SndCommand *cmd)
  75828.     = 0xA804; 
  75829. æDT OSErr myVariable = SndDoImmediate((SndChannelPtr) chan,(const SndCommand *) cmd);
  75830. æRI V-479, VI
  75831. æC 
  75832. The SndDoImmediate function operates much like SndDoCommand, except that it
  75833. bypasses the existing command queue of the sound channel and sends the specified
  75834. command directly to the synthesizer or to the first modifier. This routine also
  75835. overrides any waitCmd, pauseCmd, or syncCmd commands that may have already been
  75836. received by the synthesizer or modifiers.
  75837.  
  75838. FUNCTION SndDoImmediate (chan: SndChannelPtr; cmd: SndCommand): OSErr;
  75839.  
  75840. The chan parameter is a pointer to a sound channel. The requested command is
  75841. specified in the cmd parameter.
  75842.  
  75843. Result codes
  75844. noErr          0  No error
  75845. badChannel  –205  Channel is corrupt or unusable
  75846.  
  75847. æKY SndNewChannel
  75848. æFc Sound.h
  75849. æT Function
  75850. æTN A807
  75851. æD 
  75852. pascal OSErr SndNewChannel(SndChannelPtr *chan,short synth,long init,SndCallBackProcPtr userRoutine)
  75853.     = 0xA807; 
  75854. æDT OSErr myVariable = SndNewChannel((SndChannelPtr *) chan,(short) synth,(long) init,(SndCallBackProcPtr) userRoutine);
  75855. æMM
  75856. æRI V-477, VI
  75857. æC 
  75858. If NIL is passed as the chan parameter, SndNewChannel allocates a sound channel
  75859. record in the application’s heap and returns a pointer to that record.
  75860. Applications that allocate their own channel memory can pass a pointer to a
  75861. sound channel record in the chan parameter. Each channel holds 128 commands as a
  75862. default size. Your application can expand the length of a channel by creating
  75863. its own channel in memory.
  75864.  
  75865. The synth parameter specifies which playback synthesizer is to be used. The
  75866. application specifies a synthesizer by its resource ID, and this 'snth' resource
  75867. is loaded into memory and linked to the channel. The state of the 'snth' handle
  75868. is saved with HGetState. To create a channel without linking it to a
  75869. synthesizer, pass 0 as the synth parameter. This is useful when using SndPlay
  75870. with an 'snd ' that specifies a synthesizer ID.
  75871.  
  75872. The init parameter specifies an initialization option that should be sent to the
  75873. synthesizer when opening the channel. For example, to open the third wave table
  75874. channel, use initChan2 as the init parameter. Only the wave-table synthesizer
  75875. and sampled sound synthesizer currently use the init options. To determine if a
  75876. particular option is understood by the synthesizer, use the availableCmd command
  75877. with the SndControl routine.
  75878.  
  75879. If your application produces sounds asynchronously or needs to be alerted when a
  75880. command has completed, define a callback procedure and pass a pointer to that
  75881. procedure in the userRoutine parameter. This routine is called once the
  75882. synthesizer has received the callBackCmd command. If you pass NIL as the
  75883. userRoutine parameter, then any callBackCmd commands are ignored.
  75884.  
  75885. Result codes
  75886. noErr          0  No error
  75887. resProblem  –204  Problem loading the resource
  75888. badChannel  –205  Channel is corrupt or unusable
  75889.  
  75890.  
  75891. æKY SndDisposeChannel
  75892. æFc Sound.h
  75893. æT Function
  75894. æTN A801
  75895. æD pascal OSErr SndDisposeChannel(SndChannelPtr chan,Boolean quietNow)
  75896.     = 0xA801; 
  75897. æDT OSErr myVariable = SndDisposeChannel((SndChannelPtr) chan,(Boolean) quietNow);
  75898. æMM
  75899. æRI V-479, VI
  75900. æC 
  75901. To release the memory previously allocated to a sound channel that is no longer
  75902. needed, call SndDisposeChannel.
  75903.  
  75904. This routine disposes of the channel specified in the chan parameter and
  75905. releases all memory allocated by the Sound Manager for that channel. If an
  75906. application created its own channel record in memory or installed a sound as an
  75907. instrument, the Sound Manager does not dispose of that memory. The Sound Manager
  75908. restores the original state of 'snth' resource handles with a call to HSetState.
  75909.  
  75910. SndDisposeChannel can dispose of a channel immediately or wait until the queued
  75911. commands are processed. If quietNow is set to TRUE, a flushCmd command and then
  75912. a quietCmd command are sent to the channel. This removes all commands, stops any
  75913. sound in progress, and closes the channel. If quietNow is set to FALSE, then the
  75914. Sound Manager issues a quietCmd command only and waits until the quietCmd
  75915. command is received by the synthesizer before disposing of the channel. In this
  75916. situation, SndDisposeChannel is synchronous.
  75917.  
  75918. Result codes
  75919. noErr          0  No error
  75920. badChannel  –205  Channel is corrupt or unusable
  75921.  
  75922. æKY SndPlay
  75923. æFc Sound.h
  75924. æT Function
  75925. æTN A805
  75926. æD pascal OSErr SndPlay(SndChannelPtr chan,Handle sndHdl,Boolean async)
  75927.     = 0xA805; 
  75928. æDT OSErr myVariable = SndPlay((SndChannelPtr) chan,(Handle) sndHdl,(Boolean) async);
  75929. æRI V-477, VI
  75930. æC 
  75931. You can use the SndPlay function to play the sounds that are stored in an 'snd '
  75932. resource, either format 1 or format 2. You can use the SysBeep procedure to play
  75933. the system alert sound. Alert sounds are stored in the System Resource File as
  75934. format 1 'snd ' resources. The user selects an alert sound in the Sound control
  75935. panel. The default alert sound is a simple beep.
  75936.  
  75937. SndPlay and SysBeep are the highest-level sound routines and are generally used
  75938. separately from the other Sound Manager routines. SndPlay accepts a handle to an
  75939. 'snd ' resource as one of its parameters. Depending upon the needs of your
  75940. application, you may be able to accomplish all desired sound-related activity
  75941. simply by producing a system beep using SysBeep or, using SndPlay, by playing
  75942. other sounds that are stored as 'snd ' resources.
  75943.  
  75944. FUNCTION SndPlay (chan: SndChannelPtr; sndHdl: Handle; async: Boolean) : OSErr;
  75945.  
  75946. SndPlay attempts to play the sound specified in the 'snd ' resource located at
  75947. sndHdl. If a format 1 'snd ' resource specifies a synthesizer and any modifiers,
  75948. then the appropriate 'snth' resources are loaded into memory and linked to the
  75949. channel. All commands contained in the 'snd ' resource are then sent to the
  75950. channel.
  75951.  
  75952. The chan parameter is a pointer to a sound channel. If the application passes
  75953. NIL as the channel pointer, the Sound Manager creates a channel in the
  75954. application’s heap. The Sound Manager releases this memory after the sound has
  75955. completed. The async parameter is ignored if the application passes NIL as the
  75956. channel pointer.
  75957.  
  75958. If, however, the application does supply a channel pointer in chan, then the
  75959. sound can be produced asynchronously. When sound is played asynchronously, a
  75960. completion routine can be called when the last command has finished processing.
  75961. This procedure is the callback procedure supplied to SndNewChannel. SndPlay
  75962. calls HGetState on the 'snd ' resource before HMoveHi and HLock; once the sound
  75963. has completed, SndPlay restores the state of the 'snd ' resource’s handle with
  75964. HSetState.
  75965.  
  75966. If a format 1 'snd ' resource does not specify which synthesizer is to be used,
  75967. SndPlay defaults to the note synthesizer. SndPlay also supports format 2 'snd '
  75968. resources using the sampled sound synthesizer and a bufferCmd. Note that to use
  75969. SndPlay and the sampled sound synthesizer with a format 1 'snd ' resource, you
  75970. must include a bufferCmd command in the resource.
  75971.  
  75972. Result codes
  75973. noErr          0  No error
  75974. resProblem  –204  Problem loading the resource
  75975. badChannel  –205  Channel is corrupt or unusable
  75976. badFormat   –206  Resource is corrupt or unusable
  75977.  
  75978. †  Warning:  Do not use SndPlay with an 'snd ' that specifies a synthesizer ID
  75979. if the channel has already been linked to a synthesizer. Ê
  75980.  
  75981. æKY SndControl
  75982. æFc Sound.h
  75983. æT Function
  75984. æTN A806
  75985. æD pascal OSErr SndControl(short id,SndCommand *cmd)
  75986.     = 0xA806; 
  75987. æDT OSErr myVariable = SndControl((short) id,(SndCommand *) cmd);
  75988. æRI V-479, VI
  75989. æC 
  75990. The SndControl routine is used to send control commands directly to a
  75991. synthesizer or modifier specified by its resource ID. This can be called even if
  75992. no channel has been created for the synthesizer. This control call is used with
  75993. availableCmd or versionCmd to request information regarding a synthesizer. The
  75994. requested information is returned in the cmd parameter. SndControl is also used
  75995. with sizeCmd to determine the size of converted audio data.
  75996.  
  75997. Result codes
  75998. noErr          0  No error
  75999. badChannel  –205  Channel is corrupt or unusable
  76000.  
  76001. æKY SndSoundManagerVersion
  76002. æFc Sound.h
  76003. æT Function
  76004. æTN A800
  76005. æD 
  76006. pascal unsigned long SndSoundManagerVersion(void)
  76007.     = {MOVEL,sMgrSndSoundManagerVersion,sMgrToolNum,0xA800}; 
  76008. æDT unsigned long myVariable = SndSoundManagerVersion()(void);
  76009. æC 
  76010.  
  76011. æKY SndStartFilePlay
  76012. æFc Sound.h
  76013. æT Function
  76014. æTN A800
  76015. æD 
  76016. pascal OSErr SndStartFilePlay(SndChannelPtr theChannel,Short vRefNum,const Str63 fName,
  76017.     Short resNum,long totalSpace,Ptr theBuffer,AudioSelectionPtr theSelection,
  76018.     ProcPtr completionRtn,Boolean async)
  76019.     = {MOVEL,sMgrSndStartFilePlay,sMgrToolNum,0xA800}; 
  76020. æDT OSErr myVariable = SndStartFilePlay((SndChannelPtr) theChannel,(Short) vRefNum,(const Str63) fName,()
  76021.     Short resNum,(long) totalSpace,(Ptr) theBuffer,(AudioSelectionPtr) theSelection,()
  76022.     ProcPtr completionRtn,(Boolean) async);
  76023. æC 
  76024. SndStartFilePlay is used to initiate continuous play from disk on a sound
  76025. channel. The parameter chan is a pointer to a sound channel. If chan is not NIL,
  76026. it is used as a valid channel. If chan is NIL, an internally allocated sound
  76027. channel is used for play from disk. This internally allocated sound channel is
  76028. not passed back to the caller. Since the other two play-from-disk routines
  76029. require a SndChannelPtr, you must allocate your own channel if you wish to use
  76030. those routines.
  76031.  
  76032. The sounds you wish to play can be stored either in a file or in an 'snd '
  76033. resource. If you are playing a file, then vRefNum should be the volume reference
  76034. number of the file to be played and fName should be the name of the file to be
  76035. played. Also, if you are playing a file, the parameter resNum should be set to
  76036. 0.
  76037.  
  76038. If you are playing an 'snd ' resource, then vRefNum should be set to NIL and
  76039. fName should be a zero-length string. Also, if you are playing an 'snd '
  76040. resource, then resNum should be the resource ID number (not the file reference
  76041. number) of the resource to play. Both format 1 and format 2 'snd ' resources are
  76042. supported.
  76043.  
  76044. The totalSpace parameter contains the number of bytes of memory that the Sound
  76045. Manager is to use for input buffering while reading in sound data. If theBuffer
  76046. is a NIL pointer, then the Sound Manager internally allocates two relocatable
  76047. blocks, each of which is half the size of totalSpace; otherwise theBuffer should
  76048. be a pointer to a nonrelocatable block of size totalSpace.
  76049.  
  76050. If theSelection is a NIL pointer, then the entire sound is played; otherwise
  76051. theSelection should point to an AudioSelection structure. You use the
  76052. AudioSelection structure to specify the segment of the sound to be played.
  76053.  
  76054. If async is TRUE, then the call is made asynchronously; otherwise the call is
  76055. synchronous.
  76056.  
  76057. Result codes
  76058. noErr                    0  No error
  76059. noHardware            –200  Required sound hardware not available
  76060. notEnoughHardware     –201  Insufficient hardware available
  76061. queueFull             –203  No room in the queue
  76062. badChannel            –205  Channel is corrupt or unusable
  76063. badFormat             –206  Resource is corrupt or unusable
  76064. notEnoughBufferSpace  –207  Insufficient memory available
  76065. badFileFormat         –208  File is corrupt or unusable
  76066. channelBusy           –209  Channel is busy
  76067. buffersTooSmall       –210  Buffer is too small
  76068. resNotFound           –214  Resource not found in resource maps
  76069.  
  76070. Note:  SndStartFilePlay allocates memory so it cannot be called at interrupt
  76071. level. 
  76072.  
  76073. æKY SndPauseFilePlay
  76074. æFc Sound.h
  76075. æT Function
  76076. æTN A800
  76077. æD 
  76078. pascal OSErr SndPauseFilePlay(SndChannelPtr theChannel)
  76079.     = {MOVEL,sMgrSndPauseFilePlay,sMgrToolNum,0xA800}; 
  76080. æDT OSErr myVariable = SndPauseFilePlay((SndChannelPtr) theChannel);
  76081. æC 
  76082. SndPauseFilePlay is used in conjunction with SndStopFilePlay to control play
  76083. from disk on a sound channel. Note that this call can be made only if the
  76084. program has already called SndStartFilePlay with a valid sound channel. This
  76085. call cannot be used with a synchronous SndStartFilePlay, since by definition
  76086. program control does not return to the caller until after the sound has
  76087. completely finished playing.
  76088.  
  76089. The parameter chan should be a pointer to a valid sound channel. If the channel
  76090. is not being used for play from disk, then channelNotBusy is returned when this
  76091. call is made. If the channel is busy and paused, then play from disk is resumed.
  76092. If the channel is busy and the channel is not paused, then play from disk is
  76093. suspended.
  76094.  
  76095. Result codes
  76096. noErr              0  No error
  76097. queueFull       –203  No room in the queue
  76098. badChannel      –205  Channel is corrupt or unusable
  76099. channelNotBusy  –211  Channel not currently used
  76100.  
  76101. Note:  SndPauseFilePlay calls can be made from interrupt level.  
  76102.  
  76103. æKY SndStopFilePlay
  76104. æFc Sound.h
  76105. æT Function
  76106. æTN A800
  76107. æD pascal OSErr SndStopFilePlay(SndChannelPtr theChannel,Boolean noWait)
  76108.     = {MOVEL,sMgrSndStopFilePlay,sMgrToolNum,0xA800}; 
  76109. æDT OSErr myVariable = SndStopFilePlay((SndChannelPtr) theChannel,(Boolean) noWait);
  76110. æC 
  76111. The parameter chan should be a pointer to a valid sound channel. If noWait is
  76112. TRUE, then the play from disk stops as soon as possible and program control
  76113. returns to the caller. All asynchronous file I/O calls will have been completed
  76114. and any internally allocated memory will have been released. If noWait is FALSE,
  76115. then SndStopFilePlay lets the sound complete normally and returns only after the
  76116. sound has completed, all asynchronous file I/O calls have completed, and any
  76117. internal allocated memory has been released.
  76118.  
  76119. Note:  SndStopFilePlay calls can be made from interrupt level. 
  76120.  
  76121. Result codes
  76122. noErr          0  No error
  76123. badChannel  –205  Channel is corrupt or unusable
  76124.  
  76125. æKY SndChannelStatus
  76126. æFc Sound.h
  76127. æT Function
  76128. æTN A800
  76129. æD pascal OSErr SndChannelStatus(SndChannelPtr theChannel,Short theLength,
  76130.     SCStatusPtr theStatus)
  76131.     = {MOVEL,sMgrSndChannelStatus,sMgrToolNum,0xA800}; 
  76132. æDT OSErr myVariable = SndChannelStatus((SndChannelPtr) theChannel,(Short) theLength,()
  76133.     SCStatusPtr theStatus);
  76134. æC 
  76135. The chan parameter should be a pointer to a valid sound channel. The parameter
  76136. theLength should be the size in bytes of the scStatus structure that theStatus
  76137. points to. The parameter theStatus should be a pointer to an scStatus structure.
  76138. Upon successful completion of the call, the fields of that structure contain the
  76139. information about the specified sound channel.
  76140.  
  76141. Note:  SndChannelStatus can be called from interrupt level.  
  76142.  
  76143. Result codes
  76144. noErr          0  No error
  76145. badParam    –213  A parameter is incorrect
  76146. badChannel  –205  Channel is corrupt or unusable
  76147.  
  76148. æKY SndManagerStatus
  76149. æFc Sound.h
  76150. æT Function
  76151. æTN A800
  76152. æD 
  76153. pascal OSErr SndManagerStatus(Short theLength,SMStatusPtr theStatus)
  76154.     = {MOVEL,sMgrSndManagerStatus,sMgrToolNum,0xA800}; 
  76155. æDT OSErr myVariable = SndManagerStatus((Short) theLength,(SMStatusPtr) theStatus);
  76156. æC 
  76157. The parameter theLength should be the size in bytes of the smStatus structure.
  76158. The parameter theStatus is a pointer to a smStatus structure. SndManagerStatus
  76159. calls can be made from interrupt level.
  76160.  
  76161. Note:  SndManagerStatus can be called from interrupt level.  
  76162.  
  76163. Result codes
  76164. noErr          0  No error
  76165. badChannel  –205  Channel is corrupt or unusable
  76166.  
  76167. æKY SndGetSysBeepState
  76168. æFc Sound.h
  76169. æT Function
  76170. æTN A800
  76171. æD 
  76172. pascal void SndGetSysBeepState(Short *sysBeepState)
  76173.     = {MOVEL,sMgrSndGetSysBeepState,sMgrToolNum,0xA800}; 
  76174. æDT 
  76175. SndGetSysBeepState((Short *) sysBeepState);
  76176. æC 
  76177. SndGetSysBeepState is used to determine whether SysBeep is enabled. It returns
  76178. one of two states on return, either sysBeepDisable or sysBeepEnable.
  76179.  
  76180. æKY SndSetSysBeepState
  76181. æFc Sound.h
  76182. æT Function
  76183. æTN A800
  76184. æD 
  76185. pascal OSErr SndSetSysBeepState(Short sysBeepState)
  76186.     = {MOVEL,sMgrSndSetSysBeepState,sMgrToolNum,0xA800}; 
  76187. æDT OSErr myVariable = SndSetSysBeepState((Short) sysBeepState);
  76188. æC 
  76189. Use SndSetSysBeepState to set the state of the system beep. The sysBeepState
  76190. parameter should be set to either sysBeepDisable or sysBeepEnable.
  76191.  
  76192. Result codes
  76193. noErr              0  No error
  76194. noMoreRealTime  –212  Not enough CPU time available
  76195. badParam        –213  A parameter is incorrect
  76196.  
  76197. Note:  SndSetSysBeepState calls can be made from interrupt level.  
  76198.  
  76199. æKY SndPlayDoubleBuffer
  76200. æFc Sound.h
  76201. æT Function
  76202. æTN A800
  76203. æD 
  76204. pascal OSErr SndPlayDoubleBuffer(SndChannelPtr theChannel,SndDoubleBufferHeaderPtr theParams)
  76205.     = {MOVEL,sMgrSndPlayDoubleBuffer,sMgrToolNum,0xA800}; 
  76206. æDT OSErr myVariable = SndPlayDoubleBuffer((SndChannelPtr) theChannel,(SndDoubleBufferHeaderPtr) theParams);
  76207. æC 
  76208. SndPlayDoubleBuffer is a low-level routine that gives you maximum efficiency and
  76209. control over double buffering while still maintaining compatibility with the
  76210. Sound Manager.
  76211.  
  76212. FUNCTION SndPlayDoubleBuffer (chan: SndChannelPtr; SndDBHPtr:
  76213.                               SndDoubleBufferHeaderPtr) : OSErr;
  76214.  
  76215. The parameter chan is a valid sound channel pointer. The parameter SndDBHPtr is
  76216. a pointer to a SndDoubleBufferHeader.
  76217.  
  76218. Result codes
  76219. noErr          0  No error
  76220. badChannel  –205  Channel is corrupt or unusable
  76221.  
  76222. æKY SndGetBufferStufferLoad
  76223. æFc Sound.h
  76224. æT Function
  76225. æTN A800
  76226. æD 
  76227. pascal Short SndGetBufferStufferLoad(Short channelFeatures)
  76228.     = {MOVEL,sMgrSndGetBufferStufferLoad,sMgrToolNum,0xA800}; 
  76229. æDT Short myVariable = SndGetBufferStufferLoad((Short) channelFeatures);
  76230. æC 
  76231.  
  76232. æKY SndGetMixerLoad
  76233. æFc Sound.h
  76234. æT Function
  76235. æTN A800
  76236. æD 
  76237. pascal Short SndGetMixerLoad(Short numChannels)
  76238.     = {MOVEL,sMgrSndGetMixerLoad,sMgrToolNum,0xA800}; 
  76239. æDT Short myVariable = SndGetMixerLoad((Short) numChannels);
  76240. æC 
  76241.  
  76242. æKY MACEVersion
  76243. æFc Sound.h
  76244. æT Function
  76245. æTN A800
  76246. æD 
  76247. pascal unsigned long MACEVersion(void)
  76248.     = {MOVEL,sMgrMACEVersion,maceToolNum,0xA800}; 
  76249. æDT unsigned long myVariable = MACEVersion()(void);
  76250. æC 
  76251.  
  76252. æKY Comp3to1
  76253. æFc Sound.h
  76254. æT Function
  76255. æTN A800
  76256. æD 
  76257. void Comp3to1(Ptr inBuffer,Ptr outBuffer,unsigned long Cnt,Ptr inState,
  76258.     Ptr outState)
  76259.     = {MOVEL,sMgrComp3to1,maceToolNum,0xA800}; 
  76260. æDT 
  76261. Comp3to1((Ptr) inBuffer,(Ptr) outBuffer,(unsigned long) Cnt,(Ptr) inState,()
  76262.     Ptr outState);
  76263. æC 
  76264.  
  76265. æKY Exp1to3
  76266. æFc Sound.h
  76267. æT Function
  76268. æTN A800
  76269. æD 
  76270. void Exp1to3(Ptr inBuffer,Ptr outBuffer,unsigned long Cnt,Ptr inState,Ptr outState,
  76271.     unsigned long numChannels,unsigned long whichChannel)
  76272.     = {MOVEL,sMgrExp1to3,maceToolNum,0xA800}; 
  76273. æDT 
  76274. Exp1to3((Ptr) inBuffer,(Ptr) outBuffer,(unsigned long) Cnt,(Ptr) inState,(Ptr) outState,(
  76275.     unsigned) long numChannels,(unsigned long) whichChannel);
  76276. æC 
  76277.  
  76278. æKY Comp6to1
  76279. æFc Sound.h
  76280. æT Function
  76281. æTN A800
  76282. æD 
  76283. void Comp6to1(Ptr inBuffer,Ptr outBuffer,unsigned long Cnt,Ptr inState,
  76284.     Ptr outState)
  76285.     = {MOVEL,sMgrComp6to1,maceToolNum,0xA800}; 
  76286. æDT 
  76287. Comp6to1((Ptr) inBuffer,(Ptr) outBuffer,(unsigned long) Cnt,(Ptr) inState,()
  76288.     Ptr outState);
  76289. æC 
  76290.  
  76291. æKY Exp1to6
  76292. æFc Sound.h
  76293. æT Function
  76294. æTN A800
  76295. æD 
  76296. void Exp1to6(Ptr inBuffer,Ptr outBuffer,unsigned long Cnt,Ptr inState,Ptr outState,
  76297.     unsigned long numChannels,unsigned long whichChannel)
  76298.     = {MOVEL,sMgrExp1to6,maceToolNum,0xA800}; 
  76299. æDT 
  76300. Exp1to6((Ptr) inBuffer,(Ptr) outBuffer,(unsigned long) Cnt,(Ptr) inState,(Ptr) outState,(
  76301.     unsigned) long numChannels,(unsigned long) whichChannel);
  76302. æC 
  76303.  
  76304. æKY SetSoundVol
  76305. æFc Sound.h
  76306. æT Function
  76307. æD pascal void SetSoundVol(short level); 
  76308. æDT SetSoundVol((short) level);
  76309. æRI II-233
  76310. æC 
  76311. [Not in ROM]
  76312.  
  76313. SetSoundVol immediately sets the speaker volume to the specified level, from 0
  76314. (silent) to 7 (loudest); it doesn’t, however, change the volume setting that’s under
  76315. user control via the Control Panel desk accessory. If your application calls SetSoundVol,
  76316. it should save the current volume (using GetSoundVol) when it starts up and restore
  76317. it (with SetSoundVol) upon exit; this resets the actual speaker volume to match the
  76318. Control Panel setting.
  76319.  
  76320. Assembly-language note:  To set the speaker volume level from assembly
  76321.                          language, call this Pascal procedure from your program.
  76322.                          As a side effect, it will set the low-order three bits
  76323.                          of the global variable SdVolume to the specified level.
  76324.  
  76325. Note:  The Control Panel volume setting is stored in parameter RAM; if you’re
  76326.        writing a similar desk accessory and want to change this setting, see
  76327.        the discussion of parameter RAM in the Operating System Utilities
  76328.        chapter.
  76329.  
  76330. æKY GetSoundVol
  76331. æFc Sound.h
  76332. æT Function
  76333. æD pascal void GetSoundVol(short *level); 
  76334. æDT GetSoundVol((short *) level);
  76335. æRI II-232
  76336. æC  
  76337. [Not in ROM]
  76338.  
  76339. GetSoundVol returns the current speaker volume, from 0 (silent) to 7 (loudest).
  76340.  
  76341. Assembly-language note:  Assembly-language programmers can get the speaker
  76342.                          volume level from the low-order three bits of the
  76343.                          global variable SdVolume.
  76344.  
  76345. æKY StartSound
  76346. æFc Sound.h
  76347. æT Function
  76348. æD pascal void StartSound(Ptr synthRec,long numBytes,SndCompletionProcPtr completionRtn); 
  76349. æDT StartSound((Ptr) synthRec,(long) numBytes,(SndCompletionProcPtr) completionRtn);
  76350. æMM
  76351. æRT 19
  76352. æRI II-231, N19-1
  76353. æC 
  76354. [Not in ROM]
  76355.  
  76356. Assembly-language note:  StartSound is equivalent to a Device Manager Write
  76357.                          call with ioRefNum=–4, ioBuffer=synthRec, and
  76358.                          ioReqCount=numBytes.
  76359.  
  76360. StartSound begins producing the sound described by the synthesizer buffer pointed to
  76361. by synthRec. NumBytes indicates the size of the synthesizer buffer
  76362. (in bytes), and completionRtn points to a completion routine to be executed when the
  76363. sound finishes:
  76364.  
  76365.   •  If completionRtn is POINTER(–1), the sound will be produced synchronously.
  76366.   •  If completionRtn is NIL, the sound will be produced asynchronously, but
  76367.      no completion routine will be executed.
  76368.   •  Otherwise, the sound will be produced asynchronously and the routine
  76369.      pointed to by completionRtn will be executed when the sound finishes.
  76370.  
  76371. Warning:  You may want the completion routine to start the next sound when one
  76372.           sound finishes, but beware:  Completion routines are executed at the
  76373.           interrupt level and must preserve all registers other than A0, A1,
  76374.           and D0-D2. They must not make any calls to the Memory Manager,
  76375.           directly or indirectly, and can’t depend on handles to unlocked
  76376.           blocks being valid; be sure to preallocate all the space you’ll need.
  76377.           Or, instead of starting the next sound itself, the completion routine
  76378.           can post an application-defined event and your application’s main
  76379.           event loop can start the next sound when it gets the event.
  76380.  
  76381. Because the type of pointer for each type of synthesizer buffer is different and the
  76382. type of the synthRec parameter is Ptr, you’ll need to do something like the following
  76383. example (which applies to the free-form synthesizer):
  76384.  
  76385.   VAR  myPtr:  Ptr;
  76386.        myHandle:  Handle;
  76387.        myFFPtr:  FFSynthPtr;
  76388.        . . .
  76389.   myHandle := NewHandle(buffSize);  {allocate space for the buffer}
  76390.   HLock(myHandle);                  {lock the buffer}
  76391.   myPtr := myHandle^;               {dereference the handle}
  76392.   myFFPtr := FFSynthPtr(myPtr);     {coerce type to FFSynthPtr}
  76393.   myFFPtr^.mode := ffMode;          {identify the synthesizer}
  76394.   . . .                             {fill the buffer with values }
  76395.                                     { describing the sound}
  76396.   StartSound(myPtr,buffSize,POINTER(-1));  {produce the sound}
  76397.   HUnlock(myHandle)                        {unlock the buffer}
  76398.  
  76399. where buffSize is the number of bytes in the synthesizer buffer.
  76400.  
  76401. The sounds are generated as follows:
  76402.  
  76403.   •  Free-form synthesizer:  The magnitudes described by each byte in the
  76404.      waveform description are generated sequentially until the number of bytes
  76405.      specified by the numBytes parameter have been written.
  76406.   •  Square-wave synthesizer:  The sounds described by each sound triplet are
  76407.      generated sequentially until either the end of the buffer has been reached
  76408.      (indicated by a count, amplitude, and duration of 0 in the square-wave
  76409.      buffer), or the number of bytes specified by the numBytes parameter have
  76410.      been written.
  76411.   •  Four-tone synthesizer:  All four sounds are generated for the length of
  76412.      time specified by the duration integer in the four-tone record.
  76413.  
  76414. æKY StopSound
  76415. æFc Sound.h
  76416. æT Function
  76417. æD pascal void StopSound(void); 
  76418. æDT StopSound()(void);
  76419. æMM
  76420. æRI II-232
  76421. æC [Not in ROM]
  76422.  
  76423. StopSound immediately stops the current StartSound call (if any), executes the current
  76424. StartSound call’s completion routine (if any), and cancels any pending asynchronous
  76425. StartSound calls.
  76426.  
  76427. Assembly-language note:  To stop sound from assembly language, you can make a
  76428.                          Device Manager KillIO call (and, when using the
  76429.                          square-wave synthesizer, set the global variable
  76430.                          CurPitch to 0). Although StopSound executes the
  76431.                          completion routine of only the current StartSound
  76432.                          call, KillIO executes the completion routine of every
  76433.                          pending asynchronous call.
  76434.  
  76435. æKY SoundDone
  76436. æFc Sound.h
  76437. æT Function
  76438. æD pascal Boolean SoundDone(void); 
  76439. æDT Boolean myVariable = SoundDone()(void);
  76440. æRI II-232
  76441. æC 
  76442. [Not in ROM]
  76443.  
  76444. SoundDone returns TRUE if the Sound Driver isn’t currently producing sound and there
  76445. are no asynchronous StartSound calls pending; otherwise it returns FALSE.
  76446.  
  76447. Assembly-language note:  Assembly-language programmers can poll the ioResult
  76448.                          field of the most recent Device Manager Write call’s
  76449.                          parameter block to determine when the Write call
  76450.                          finishes.
  76451.  
  76452. æKY SndAddModifier
  76453. æFc Sound.h
  76454. æT Function
  76455. æD pascal OSErr SndAddModifier(SndChannelPtr chan,SndModifierProcPtr modifier,
  76456.     short id,long init)
  76457.     = 0xA802; 
  76458. æDT OSErr myVariable = SndAddModifier((SndChannelPtr) chan,(SndModifierProcPtr) modifier,()
  76459.     short id,(long) init);
  76460. æMM
  76461. æRI V-478, VI
  76462. æC 
  76463. You can add a modifier to a previously created sound channel by calling
  76464. SndAddModifier.
  76465.  
  76466. Use this function to install a modifier into an open channel specified in the
  76467. chan parameter. The modifier is installed in front of the synthesizer or any
  76468. existing modifiers in the channel. If the modifier is saved as an 'snth'
  76469. resource, you should pass NIL for the ProcPtr and specify its resource ID in the
  76470. id parameter. This causes the Sound Manager to load the 'snth' resource, lock it
  76471. in memory, and link it to the channel specified. The state of the 'snth'
  76472. resource handle is saved with HGetState.
  76473.  
  76474. Note:  Having too many modifiers per channel may degrade performance.  
  76475.  
  76476. Result codes
  76477. noErr          0  No error
  76478. resProblem  –204  Problem loading the resource
  76479. badChannel  –205  Channel is corrupt or unusable
  76480.  
  76481.  
  76482. æKY StandardFile.h
  76483. æKL CustomGetFile
  76484. CustomPutFile
  76485. sfgetfile
  76486. SFGetFile
  76487. sfpgetfile
  76488. SFPGetFile
  76489. sfpputfile
  76490. SFPPutFile
  76491. SFPutFile
  76492. sfputfile
  76493. StandardGetFile
  76494. StandardPutFile
  76495.  
  76496. ActivateCBProcPtr
  76497. DlgHookCBProcPtr
  76498. DlgHookProcPtr
  76499. FileFilterCBProcPtr
  76500. FileFilterProcPtr
  76501. getCancel
  76502. getDlgID
  76503. getDrive
  76504. getEject
  76505. getNmList
  76506. getOpen
  76507. getScroll
  76508. hookCharOffset
  76509. hookFirstCall
  76510. hookFolderPopUp
  76511. hookGotoAliasTarget
  76512. hookGotoDesktop
  76513. hookGotoNextDrive
  76514. hookGotoParent
  76515. hookGotoPrevDrive
  76516. hookLastCall
  76517. hookNullEvent
  76518. hookOpenAlias
  76519. hookOpenFolder
  76520. hookRebuildList
  76521. hookSetActiveOffset
  76522. ModalFilterCBProcPtr
  76523. ModalFilterProcPtr
  76524. putCancel
  76525. putDlgID
  76526. putDrive
  76527. putEject
  76528. putName
  76529. putSave
  76530. SFReply
  76531. SFTypeList
  76532. StandardFileReply
  76533.  
  76534. æKY putDlgID
  76535. æFc StandardFile.h
  76536. æT #define
  76537. æD #define putDlgID -3999
  76538. æC 
  76539.  
  76540. æKY putSave
  76541. æFc StandardFile.h
  76542. æT #define
  76543. æD #define putSave 1
  76544. æC 
  76545.  
  76546. æKY putCancel
  76547. æFc StandardFile.h
  76548. æT #define
  76549. æD #define putCancel 2
  76550. æC 
  76551.  
  76552. æKY putEject
  76553. æFc StandardFile.h
  76554. æT #define
  76555. æD #define putEject 5
  76556. æC 
  76557.  
  76558. æKY putDrive
  76559. æFc StandardFile.h
  76560. æT #define
  76561. æD #define putDrive 6
  76562. æC 
  76563.  
  76564. æKY putName
  76565. æFc StandardFile.h
  76566. æT #define
  76567. æD #define putName 7
  76568. æC 
  76569.  
  76570. æKY getDlgID
  76571. æFc StandardFile.h
  76572. æT #define
  76573. æD #define getDlgID -4000
  76574. æC 
  76575.  
  76576. æKY getOpen
  76577. æFc StandardFile.h
  76578. æT #define
  76579. æD #define getOpen 1
  76580. æC 
  76581.  
  76582. æKY getCancel
  76583. æFc StandardFile.h
  76584. æT #define
  76585. æD #define getCancel 3
  76586. æC 
  76587.  
  76588. æKY getEject
  76589. æFc StandardFile.h
  76590. æT #define
  76591. æD #define getEject 5
  76592. æC 
  76593.  
  76594. æKY getDrive
  76595. æFc StandardFile.h
  76596. æT #define
  76597. æD #define getDrive 6
  76598. æC 
  76599.  
  76600. æKY getNmList
  76601. æFc StandardFile.h
  76602. æT #define
  76603. æD #define getNmList 7
  76604. æC 
  76605.  
  76606. æKY getScroll
  76607. æFc StandardFile.h
  76608. æT #define
  76609. æD #define getScroll 8
  76610. æC 
  76611.  
  76612. æKY hookFirstCall
  76613. æFc StandardFile.h
  76614. æT #define
  76615. æD 
  76616. /*  duumy item numbers for use in DlgHook  */
  76617.  
  76618. #define hookFirstCall (-1)
  76619. æC 
  76620.  
  76621. æKY hookCharOffset
  76622. æFc StandardFile.h
  76623. æT #define
  76624. æD #define hookCharOffset 0x1000
  76625. æC 
  76626.  
  76627. æKY hookNullEvent
  76628. æFc StandardFile.h
  76629. æT #define
  76630. æD #define hookNullEvent 100
  76631. æC 
  76632.  
  76633. æKY hookRebuildList
  76634. æFc StandardFile.h
  76635. æT #define
  76636. æD #define hookRebuildList 101
  76637. æC 
  76638.  
  76639. æKY hookFolderPopUp
  76640. æFc StandardFile.h
  76641. æT #define
  76642. æD #define hookFolderPopUp 102
  76643. æC 
  76644.  
  76645. æKY hookOpenFolder
  76646. æFc StandardFile.h
  76647. æT #define
  76648. æD #define hookOpenFolder 103
  76649. æC 
  76650.  
  76651. æKY hookOpenAlias
  76652. æFc StandardFile.h
  76653. æT #define
  76654. æD 
  76655. /*  the following are only in system 7.0+ 
  76656.  */
  76657.  
  76658. #define hookOpenAlias 104
  76659. æC 
  76660.  
  76661. æKY hookGotoDesktop
  76662. æFc StandardFile.h
  76663. æT #define
  76664. æD #define hookGotoDesktop 105
  76665. æC 
  76666.  
  76667. æKY hookGotoAliasTarget
  76668. æFc StandardFile.h
  76669. æT #define
  76670. æD #define hookGotoAliasTarget 106
  76671. æC 
  76672.  
  76673. æKY hookGotoParent
  76674. æFc StandardFile.h
  76675. æT #define
  76676. æD #define hookGotoParent 107
  76677. æC 
  76678.  
  76679. æKY hookGotoNextDrive
  76680. æFc StandardFile.h
  76681. æT #define
  76682. æD #define hookGotoNextDrive 108
  76683. æC 
  76684.  
  76685. æKY hookGotoPrevDrive
  76686. æFc StandardFile.h
  76687. æT #define
  76688. æD #define hookGotoPrevDrive 109
  76689. æC 
  76690.  
  76691. æKY hookSetActiveOffset
  76692. æFc StandardFile.h
  76693. æT #define
  76694. æD #define hookSetActiveOffset 200
  76695. æC 
  76696.  
  76697. æKY hookLastCall
  76698. æFc StandardFile.h
  76699. æT #define
  76700. æD #define hookLastCall (-2)
  76701. æC 
  76702.  
  76703. æKY DlgHookProcPtr
  76704. æFc StandardFile.h
  76705. æT typedef
  76706. æD typedef pascal short (*DlgHookProcPtr)(short item, DialogPtr theDialog);
  76707. æC 
  76708.  
  76709. æKY ModalFilterProcPtr
  76710. æFc StandardFile.h
  76711. æT typedef
  76712. æD typedef pascal Boolean (*ModalFilterCBProcPtr)(DialogPtr theDialog, EventRecord *theEvent, short *itemHit, void *callBackPtr);
  76713. æC 
  76714.  
  76715. æKY FileFilterProcPtr
  76716. æFc StandardFile.h
  76717. æT typedef
  76718. æD typedef pascal Boolean (*FileFilterProcPtr)(ParmBlkPtr PB);
  76719. æC 
  76720.  
  76721. æKY DlgHookCBProcPtr
  76722. æFc StandardFile.h
  76723. æT typedef
  76724. æD 
  76725. /* the following also include an extra parameter of "callBack pointer" */
  76726. typedef pascal short (*DlgHookCBProcPtr)(short item, DialogPtr theDialog, void *callBackPtr);
  76727. æC 
  76728.  
  76729. æKY ModalFilterCBProcPtr
  76730. æFc StandardFile.h
  76731. æT typedef
  76732. æD typedef pascal Boolean (*ModalFilterCBProcPtr)(DialogPtr theDialog, EventRecord *theEvent, short *itemHit, void *callBackPtr);
  76733. æC 
  76734.  
  76735. æKY FileFilterCBProcPtr
  76736. æFc StandardFile.h
  76737. æT typedef
  76738. æD typedef pascal Boolean (*FileFilterCBProcPtr)(ParmBlkPtr PB, void *callBackPtr);
  76739. æC 
  76740.  
  76741. æKY ActivateCBProcPtr
  76742. æFc StandardFile.h
  76743. æT typedef
  76744. æD typedef pascal void (*ActivateCBProcPtr)(DialogPtr theDialog, short itemNo, Boolean activating, void *callBackPtr);
  76745. æC 
  76746.  
  76747. æKY SFTypeList
  76748. æFc StandardFile.h
  76749. æT typedef
  76750. æD 
  76751. typedef OSType SFTypeList[4];
  76752. æC 
  76753.  
  76754. æKY SFReply
  76755. æFc StandardFile.h
  76756. æT struct
  76757. æD struct SFReply {
  76758.     Boolean good;
  76759.     Boolean copy;
  76760.     OSType fType;
  76761.     short vRefNum;
  76762.     short version;
  76763.     Str63 fName;
  76764. };
  76765.  
  76766. typedef struct SFReply SFReply;
  76767. æC 
  76768.  
  76769. æKY StandardFileReply
  76770. æFc StandardFile.h
  76771. æT struct
  76772. æD struct StandardFileReply {
  76773.     Boolean sfGood;
  76774.     Boolean sfReplacing;
  76775.     OSType sfType;
  76776.     CanonicalFileSpec sfFile;
  76777.     short sfScript;
  76778.     short sfFlags;
  76779.     Boolean sfIsFolder;
  76780.     Boolean sfIsVolume;
  76781.     long sfReserved1;
  76782.     short sfReserved2;
  76783. };
  76784.  
  76785. typedef struct StandardFileReply StandardFileReply;
  76786. æC 
  76787.  
  76788. æKY sfpputfile
  76789. æFc StandardFile.h
  76790. æT Function
  76791. æD void sfpputfile(Point *where,char *prompt,char *origName,DlgHookProcPtr dlgHook,
  76792.     SFReply *reply,short dlgID,ModalFilterProcPtr filterProc); 
  76793. æDT sfpputfile((Point *) where,(char *) prompt,(char *) origName,(DlgHookProcPtr) dlgHook,(
  76794.     SFReply) * reply,(short) dlgID,(ModalFilterProcPtr) filterProc);
  76795. æC 
  76796.  
  76797. æKY sfgetfile
  76798. æFc StandardFile.h
  76799. æT Function
  76800. æD void sfgetfile(Point *where,char *prompt,FileFilterProcPtr fileFilter,short numTypes,
  76801.     SFTypeList typeList,DlgHookProcPtr dlgHook,SFReply *reply); 
  76802. æDT sfgetfile((Point *) where,(char *) prompt,(FileFilterProcPtr) fileFilter,(short) numTypes,()
  76803.     SFTypeList typeList,(DlgHookProcPtr) dlgHook,(SFReply *) reply);
  76804. æC 
  76805.  
  76806. æKY sfpgetfile
  76807. æFc StandardFile.h
  76808. æT Function
  76809. æD void sfpgetfile(Point *where,char *prompt,FileFilterProcPtr fileFilter,
  76810.     short numTypes,SFTypeList typeList,DlgHookProcPtr dlgHook,SFReply *reply,
  76811.     short dlgID,ModalFilterProcPtr filterProc); 
  76812. æDT sfpgetfile((Point *) where,(char *) prompt,(FileFilterProcPtr) fileFilter,()
  76813.     short numTypes,(SFTypeList) typeList,(DlgHookProcPtr) dlgHook,(SFReply *) reply,()
  76814.     short dlgID,(ModalFilterProcPtr) filterProc);
  76815. æC 
  76816.  
  76817. æKY sfputfile
  76818. æFc StandardFile.h
  76819. æT Function
  76820. æD void sfputfile(Point *where,char *prompt,char *origName,DlgHookProcPtr dlgHook,
  76821.     SFReply *reply); 
  76822. æDT sfputfile((Point *) where,(char *) prompt,(char *) origName,(DlgHookProcPtr) dlgHook,(
  76823.     SFReply) * reply);
  76824. æC 
  76825.  
  76826. æKY SFPutFile
  76827. æFc StandardFile.h
  76828. æT Function
  76829. æTN A9EA
  76830. æD pascal void SFPutFile(Point where,const Str255 prompt,const Str255 origName,
  76831.     DlgHookProcPtr dlgHook,SFReply *reply)
  76832.     = {0x3F3C,0x0001,0xA9EA}; 
  76833. æDT SFPutFile((Point) where,(const Str255) prompt,(const Str255) origName,()
  76834.     DlgHookProcPtr dlgHook,(SFReply *) reply);
  76835. æC 
  76836. SFPutFile displays a dialog box allowing the user to specify a file to which data
  76837. will be written (as during a Save or Save As command). It then repeatedly gets and
  76838. handles events until the user either confirms the command after entering an appropriate
  76839. file name or aborts the command by clicking Cancel in the dialog. It reports the
  76840. user’s reply by filling the fields of the reply record specified by the reply parameter,
  76841. as described above; the fType field of this record isn’t used.
  76842.  
  76843. The general appearance of the standard SFPutFile dialog box is shown in Figure 3. The
  76844. where parameter specifies the location of the top left corner of the dialog box in
  76845. global coordinates. The prompt parameter is a line of text to be displayed as a
  76846. statText item in the dialog box, where shown in Figure 3. The origName parameter
  76847. contains text that appears as an enabled, selected editText item; for the standard
  76848. document-saving commands, it should be the current name of the document, or the empty
  76849. string (to display an insertion point) if the document hasn’t been named yet.
  76850.  
  76851. If you want to use the standard SFPutFile dialog box, pass NIL for dlgHook; otherwise,
  76852. see the information for advanced programmers below.
  76853.  
  76854. SFPutFile repeatedly calls the Dialog Manager procedure ModalDialog. When an event
  76855. involving an enabled dialog item occurs, ModalDialog handles the event and returns
  76856. the item number, and SFPutFile responds as follows:
  76857.  
  76858.   •  If the Eject or Drive button is clicked, or a disk is inserted,
  76859.      SFPutFile responds as described above under “About the Standard File
  76860.      Package”.
  76861.   •  Text entered into the editText item is stored in the fName field of
  76862.      the reply record. (SFPutFile keeps track of whether there’s currently
  76863.      any text in the item, and makes the Save button inactive if not.)
  76864.   •  If the Save button is clicked, SFPutFile determines whether the file
  76865.      name in the fName field of the reply record is appropriate. If so, it
  76866.      returns control to the application with the first field of the reply
  76867.      record set to TRUE; otherwise, it responds accordingly, as described
  76868.      below.
  76869.   •  If the Cancel button in the dialog is clicked, SFPutFile returns control
  76870.      to the application with the first field of the reply record set to FALSE.
  76871.  
  76872. Note:  Notice that disk insertion is one of the user actions listed above,
  76873.        even though ModalDialog normally ignores disk-inserted events. The
  76874.        reason this works is that SFPutFile calls ModalDialog with a
  76875.        filterProc function that lets it receive disk-inserted events.
  76876.  
  76877. The situations that may cause an entered name to be inappropriate, and SFPutFile’s
  76878. response to each, are as follows:
  76879.  
  76880.   •  If a file with the specified name already exists on the disk and is
  76881.      different from what was passed in the origName parameter, the alert
  76882.      in Figure 5 is displayed. If the user clicks Yes, the file name is
  76883.      appropriate.
  76884.  
  76885. •••Refer to Figure 5.•••
  76886.  
  76887. Figure 5–Alert for Existing File
  76888.  
  76889.   •  If the disk to which the file should be written is locked, the alert
  76890.      in Figure 6 is displayed. If a system error occurs, a similar alert
  76891.      is displayed, with the message “A system error occurred; please try
  76892.      again” (this is unrelated to the fatal system errors reported by the
  76893.      System Error Handler).
  76894.  
  76895. •••Refer to Figure 6.•••
  76896.  
  76897. Figure 6–Alert for Locked Disk
  76898.  
  76899. Note:  The user may specify a disk name (preceding the file name and
  76900.        separated from it by a colon). If the disk isn’t currently in a
  76901.        drive, an alert similar to the one in Figure 6 is displayed.
  76902.        The ability to specify a disk name is supported for historical
  76903.        reasons only; users should not be encouraged to do it.
  76904.  
  76905. After the user clicks No or Cancel in response to one of these alerts, SFPutFile
  76906. dismisses the alert box and continues handling events (so a different name may be
  76907. entered).
  76908.  
  76909. Advanced programmers:  You can create your own dialog box rather than use the
  76910.                        standard SFPutFile dialog. However, future compatibility
  76911.                        is not guaranteed if you don’t use the standard
  76912.                        SFPutFile dialog. To create a nonstandard dialog, you
  76913.                        must provide your own dialog template and store it in
  76914.                        your application’s resource file with the same resource
  76915.                        ID that the standard template has in the system resource
  76916.                        file:
  76917.  
  76918.                          CONST putDlgID = -3999; {SFPutFile dialog template ID}
  76919.  
  76920. •••Refer to Technical Note #47:•••
  76921.  
  76922. Note:  The SFPPutFile procedure, described below, lets you use any resource
  76923.        ID for your nonstandard dialog box.
  76924.  
  76925. Your dialog template must specify that the dialog window be invisible, and your
  76926. dialog must contain all the standard items, as listed below. The appearance and
  76927. location of these items in your dialog may be different. You can make an item
  76928. “invisible” by giving it a display rectangle that’s off the screen. The display
  76929. rectangle for each item in the standard dialog box is given below. The rectangle for
  76930. the standard dialog box itself is (0,0)(304,104).
  76931.  
  76932.   Item number  Item                         Standard display rectangle
  76933.  
  76934.       1        Save button                  (12,74)(82,92)
  76935.       2        Cancel button                (114,74)(184,92)
  76936.       3        Prompt string (statText)     (12,12)(184,28)
  76937.       4        UserItem for disk name       (209,16)(295,34)
  76938.       5        Eject button                 (217,43)(287,61)
  76939.       6        Drive button                 (217,74)(287,92)
  76940.       7        EditText item for file name  (14,34)(182,50)
  76941.       8        UserItem for dotted line     (200,16)(201,88)
  76942.  
  76943. Note:  Remember that the display rectangle for any “invisible” text item must
  76944.        be at least about 20 pixels wide.
  76945.  
  76946. If your dialog has additional items beyond the standard ones, or if you want to
  76947. handle any of the standard items in a nonstandard manner, you must write your own
  76948. dlgHook function and point to it with dlgHook. Your dlgHook function should have two
  76949. parameters and return an integer value. For example, this is how it would be declared
  76950. if it were named MyDlg:
  76951.  
  76952. FUNCTION MyDlg (item:  INTEGER; theDialog:  DialogPtr) :  INTEGER;
  76953.  
  76954. Immediately after calling ModalDialog, SFPutFile calls your dlgHook function, passing
  76955. it the item number returned by ModalDialog and a pointer to the dialog record describing
  76956. your dialog box. Using these two parameters, your dlgHook function should determine
  76957. how to handle the event. There are predefined constants for the item numbers of
  76958. standard enabled items, as follows:
  76959.  
  76960. CONST  putSave    = 1;    {Save button}
  76961.        putCancel  = 2;    {Cancel button}
  76962.        putEject   = 5;    {Eject button}
  76963.        putDrive   = 6;    {Drive button}
  76964.        putName    = 7;    {editText item for file name}
  76965.  
  76966. After handling the event (or, perhaps, after ignoring it) the dlgHook function must
  76967. return an item number to SFPutFile. If the item number is one of those listed above,
  76968. SFPutFile responds in the standard way; otherwise, it does nothing.
  76969.  
  76970. Note:  For advanced programmers who want to change the appearance of the
  76971.        alerts displayed when an inappropriate file name is entered, the
  76972.        resource IDs of those alerts in the system resource file are listed
  76973.        below.
  76974.  
  76975.          Alert             Resource ID
  76976.          Disk not found       –3994
  76977.          System error         –3995
  76978.          Existing file        –3996
  76979.          Locked disk          –3997
  76980.  
  76981. Assembly-Language Information
  76982.  
  76983. Constants
  76984.  
  76985. ; SFPutFile dialog template ID
  76986.  
  76987. putDlgID    .EQU    -3999
  76988.  
  76989. ; Item numbers of enabled items in SFPutFile dialog
  76990.  
  76991. putSave     .EQU    1    ;Save button
  76992. putCancel   .EQU    2    ;Cancel button
  76993. putEject    .EQU    5    ;Eject button
  76994. putDrive    .EQU    6    ;Drive button
  76995. putName     .EQU    7    ;editText item for file name
  76996.  
  76997. ; SFGetFile dialog template ID
  76998.  
  76999. getDlgID    .EQU    -4000
  77000.  
  77001. ; Item numbers of enabled items in SFGetFile dialog
  77002.  
  77003. getOpen     .EQU    1    ;Open button
  77004. getCancel   .EQU    3    ;Cancel button
  77005. getEject    .EQU    5    ;Eject button
  77006. getDrive    .EQU    6    ;Drive button
  77007. getNmList   .EQU    7    ;userItem for file name list
  77008. getScroll   .EQU    8    ;userItem for scroll bar
  77009.  
  77010. ; Routine selectors
  77011.  
  77012. sfPutFile   .EQU    1
  77013. sfGetFile   .EQU    2
  77014. sfPPutFile  .EQU    3
  77015. sfPGetFile  .EQU    4
  77016.  
  77017. Reply Record Data Structure
  77018.  
  77019. rGood       0 if ignore command (byte)
  77020. rType       File type (long)
  77021. rVolume     Volume reference number (word)
  77022. rVersion    File’s version number (word)
  77023. rName       File name (length byte followed by up to 63 characters)
  77024.  
  77025. Trap Macro Name
  77026.  
  77027. _Pack3
  77028.  
  77029. Variables
  77030.  
  77031. SFSaveDisk    Negative of volume reference number used by
  77032.               Standard File Package (word)
  77033. CurDirStore   Directory ID of directory last opened (long)
  77034. SFSaveDisk    Negative of volume reference number (word)
  77035.  
  77036. æKY SFGetFile
  77037. æFc StandardFile.h
  77038. æT Function
  77039. æTN A9EA
  77040. æD pascal void SFGetFile(Point where,const Str255 prompt,FileFilterProcPtr fileFilter,
  77041.     short numTypes,SFTypeList typeList,DlgHookProcPtr dlgHook,SFReply *reply)
  77042.     = {0x3F3C,0x0002,0xA9EA}; 
  77043. æDT SFGetFile((Point) where,(const Str255) prompt,(FileFilterProcPtr) fileFilter,()
  77044.     short numTypes,(SFTypeList) typeList,(DlgHookProcPtr) dlgHook,(SFReply *) reply);
  77045. æC 
  77046. SFGetFile displays a dialog box listing the names of a specific group of files from
  77047. which the user can select one to be opened (as during an Open command). It then
  77048. repeatedly gets and handles events until the user either confirms the command after
  77049. choosing a file name or aborts the command by clicking Cancel in the dialog. It
  77050. reports the user’s reply by filling the fields of the reply record specified by the
  77051. reply parameter, as described above under “Using the Standard File Package”.
  77052.  
  77053. The general appearance of the standard SFGetFile dialog box is shown in Figure 1.
  77054. File names are sorted in order of the ASCII codes of their characters, ignoring
  77055. diacritical marks and mapping lowercase characters to their uppercase equivalents. If
  77056. there are more file names than can be displayed at one time, the scroll bar is active;
  77057. otherwise, the scroll bar is inactive.
  77058.  
  77059. The where parameter specifies the location of the top left corner of the dialog box
  77060. in global coordinates. The prompt parameter is ignored; it’s there for historical
  77061. purposes only.
  77062.  
  77063. The fileFilter, numTypes, and typeList parameters determine which files appear in the
  77064. dialog box. SFGetFile first looks at numTypes and typeList to determine what types of
  77065. files to display, then it executes the function pointed to by fileFilter (if any) to
  77066. do additional filtering on which files to display. File types are discussed in the
  77067. Finder Interface chapter. For example, if the application is concerned only with
  77068. pictures, you won’t want to display the names of any text files.
  77069.  
  77070. Pass –1 for numTypes to display all types of files; otherwise, pass the number of
  77071. file types (up to 4) that you want to display, and pass the types themselves in
  77072. typeList. The SFTypeList data type is defined as follows:
  77073.  
  77074. TYPE SFTypeList = ARRAY[0..3] OF OSType;
  77075.  
  77076. Assembly-language note:  If you need to specify more than four types, pass a
  77077.                          pointer to an array with the desired number of entries.
  77078.  
  77079. If fileFilter isn’t NIL, SFGetFile executes the function it points to for each file,
  77080. to determine whether the file should be displayed. The fileFilter function has one
  77081. parameter and returns a Boolean value. For example:
  77082.  
  77083. FUNCTION MyFileFilter (paramBlock:  ParmBlkPtr) :  BOOLEAN;
  77084.  
  77085. SFGetFile passes this function the file information it gets by calling the File
  77086. Manager procedure GetFileInfo (see the File Manager chapter for details). The function
  77087. selects which files should appear in the dialog by returning FALSE for every file
  77088. that should be shown and TRUE for every file that shouldn’t be shown.
  77089.  
  77090. Note:  As described in the File Manager chapter, a flag can be set that tells
  77091.        the Finder not to display a particular file’s icon on the desktop;
  77092.        this has no effect on whether SFGetFile will list the file name.
  77093.  
  77094. If you want to use the standard SFGetFile dialog box, pass NIL for dlgHook; otherwise,
  77095. see the information for advanced programmers below.
  77096.  
  77097. Like SFPutFile, SFGetFile repeatedly calls the Dialog Manager procedure ModalDialog.
  77098. When an event involving an enabled dialog item occurs, ModalDialog handles the event
  77099. and returns the item number, and SFGetFile responds as follows:
  77100.  
  77101.   •  If the Eject or Drive button is clicked, or a disk is inserted,
  77102.      SFGetFile responds as described above under “About the Standard File
  77103.      Package”.
  77104.   •  If clicking or dragging occurs in the scroll bar, the contents of the
  77105.      dialog box are redrawn accordingly.
  77106.   •  If a file name is clicked, it’s selected and stored in the fName field
  77107.      of the reply record. (SFGetFile keeps track of whether a file name is
  77108.      currently selected, and makes the Open button inactive if not.)
  77109.   •  If the Open button is clicked, SFGetFile returns control to the
  77110.      application with the first field of the reply record set to TRUE.
  77111.   •  If a file name is double-clicked, SFGetFile responds as if the user
  77112.      clicked the file name and then the Open button.
  77113.   •  If the Cancel button in the dialog is clicked, SFGetFile returns control
  77114.      to the application with the first field of the reply record set to FALSE.
  77115.  
  77116. If a character key is pressed, SFGetFile selects the first file name starting with
  77117. the character typed, scrolling the list of names if necessary to show the selection.
  77118. If no file name starts with the character, SFGetFile selects the first file name
  77119. starting with a character whose ASCII code is greater than the character typed.
  77120.  
  77121. Advanced programmers:  You can create your own dialog box rather than use the
  77122.                        standard SFGetFile dialog. However, future compatibility
  77123.                        is not guaranteed if you don’t use the standard
  77124.                        SFGetFile dialog. To create a nonstandard dialog, you
  77125.                        must provide your own dialog template and store it in
  77126.                        your application’s resource file with the same resource
  77127.                        ID that the standard template has in the system resource
  77128.                        file:
  77129.  
  77130.                          CONST getDlgID = -4000; {SFGetFile dialog template ID}
  77131.  
  77132. Note:  The SFPGetFile procedure, described below, lets you use any resource
  77133.        ID for your nonstandard dialog box.
  77134.  
  77135. Your dialog template must specify that the dialog window be invisible, and your
  77136. dialog must contain all the standard items, as listed below. The appearance and
  77137. location of these items in your dialog may be different. You can make an item
  77138. “invisible” by giving it a display rectangle that’s off the screen. The display
  77139. rectangle for each item in the standard dialog box is given below. The rectangle for
  77140. the standard dialog box itself is (0,0)(348,136).
  77141.  
  77142.   Item number    Item                           Standard display rectangle
  77143.  
  77144.       1          Open button                    (152,28)(232,46)
  77145.       2          Invisible button               (1152,59)(1232,77)
  77146.       3          Cancel button                  (152,90)(232,108)
  77147.       4          UserItem for disk name         (248,28)(344,46)
  77148.       5          Eject button                   (256,59)(336,77)
  77149.       6          Drive button                   (256,90)(336,108)
  77150.       7          UserItem for file name list    (12,11)(125,125)
  77151.       8          UserItem for scroll bar        (124,11)(140,125)
  77152.       9          UserItem for dotted line       (244,20)(245,116)
  77153.      10          Invisible text (statText)      (1044,20)(1145,116)
  77154.  
  77155. If your dialog has additional items beyond the standard ones, or if you want to
  77156. handle any of the standard items in a nonstandard manner, you must write your own
  77157. dlgHook function and point to it with dlgHook. Your dlgHook function should have two
  77158. parameters and return an integer value. For example, this is how it would be declared
  77159. if it were named MyDlg:
  77160.  
  77161. FUNCTION MyDlg (item:  INTEGER; theDialog:  DialogPtr) :  INTEGER;
  77162.  
  77163. Immediately after calling ModalDialog, SFGetFile calls your dlgHook function, passing
  77164. it the item number returned by ModalDialog and a pointer to the dialog record describing
  77165. your dialog box. Using these two parameters, your dlgHook function should determine
  77166. how to handle the event. There are predefined constants for the item numbers of
  77167. standard enabled items, as follows:
  77168.  
  77169. CONST  getOpen    = 1;    {Open button}
  77170.        getCancel  = 3;    {Cancel button}
  77171.        getEject   = 5;    {Eject button}
  77172.        getDrive   = 6;    {Drive button}
  77173.        getNmList  = 7;    {userItem for file name list}
  77174.        getScroll  = 8;    {userItem for scroll bar}
  77175.  
  77176. ModalDialog also returns “fake” item numbers in the following situations, which are
  77177. detected by its filterProc function:
  77178.  
  77179.   •  When it receives a null event, it returns 100. Note that since it calls
  77180.      GetNextEvent with a mask that excludes disk-inserted events, ModalDialog
  77181.      sees them as null events, too.
  77182.   •  When a key-down event occurs, it returns 1000 plus the ASCII code of the
  77183.      character.
  77184.  
  77185. After handling the event (or, perhaps, after ignoring it) your dlgHook function must
  77186. return an item number to SFGetFile. If the item number is one of those listed above,
  77187. SFGetFile responds in the standard way; otherwise, it does nothing.
  77188.  Assembly-Language Information
  77189.  
  77190. Constants
  77191.  
  77192. ; SFPutFile dialog template ID
  77193.  
  77194. putDlgID    .EQU    -3999
  77195.  
  77196. ; Item numbers of enabled items in SFPutFile dialog
  77197.  
  77198. putSave     .EQU    1    ;Save button
  77199. putCancel   .EQU    2    ;Cancel button
  77200. putEject    .EQU    5    ;Eject button
  77201. putDrive    .EQU    6    ;Drive button
  77202. putName     .EQU    7    ;editText item for file name
  77203.  
  77204. ; SFGetFile dialog template ID
  77205.  
  77206. getDlgID    .EQU    -4000
  77207.  
  77208. ; Item numbers of enabled items in SFGetFile dialog
  77209.  
  77210. getOpen     .EQU    1    ;Open button
  77211. getCancel   .EQU    3    ;Cancel button
  77212. getEject    .EQU    5    ;Eject button
  77213. getDrive    .EQU    6    ;Drive button
  77214. getNmList   .EQU    7    ;userItem for file name list
  77215. getScroll   .EQU    8    ;userItem for scroll bar
  77216.  
  77217. ; Routine selectors
  77218.  
  77219. sfPutFile   .EQU    1
  77220. sfGetFile   .EQU    2
  77221. sfPPutFile  .EQU    3
  77222. sfPGetFile  .EQU    4
  77223.  
  77224. Reply Record Data Structure
  77225.  
  77226. rGood       0 if ignore command (byte)
  77227. rType       File type (long)
  77228. rVolume     Volume reference number (word)
  77229. rVersion    File’s version number (word)
  77230. rName       File name (length byte followed by up to 63 characters)
  77231.  
  77232. Trap Macro Name
  77233.  
  77234. _Pack3
  77235.  
  77236. Variables
  77237.  
  77238. SFSaveDisk    Negative of volume reference number used by
  77239.               Standard File Package (word)
  77240. CurDirStore   Directory ID of directory last opened (long)
  77241. SFSaveDisk    Negative of volume reference number (word)
  77242.  
  77243. æKY SFPPutFile
  77244. æFc StandardFile.h
  77245. æT Function
  77246. æTN A9EA
  77247. æD pascal void SFPPutFile(Point where,const Str255 prompt,const Str255 origName,
  77248.     DlgHookProcPtr dlgHook,SFReply *reply,short dlgID,ModalFilterProcPtr filterProc)
  77249.     = {0x3F3C,0x0003,0xA9EA}; 
  77250. æDT SFPPutFile((Point) where,(const Str255) prompt,(const Str255) origName,()
  77251.     DlgHookProcPtr dlgHook,(SFReply *) reply,(short) dlgID,(ModalFilterProcPtr) filterProc);
  77252. æC 
  77253. SFPPutFile is an alternative to SFPutFile for advanced programmers who want to use a
  77254. nonstandard dialog box. It’s the same as SFPutFile except for the two additional
  77255. parameters dlgID and filterProc.
  77256.  
  77257. DlgID is the resource ID of the dialog template to be used instead of the standard
  77258. one (so you can use whatever ID you wish rather than the same one as the standard).
  77259.  
  77260. The filterProc parameter determines how ModalDialog will filter events when called by
  77261. SFPPutFile. If filterProc is NIL, ModalDialog does the standard filtering that it
  77262. does when called by SFPutFile; otherwise, filterProc should point to a function for
  77263. ModalDialog to execute after doing the standard filtering. The function must be the
  77264. same as one you would pass directly to ModalDialog in its filterProc parameter. (See
  77265. the Dialog Manager chapter for more information.)
  77266.  
  77267. Assembly-Language Information
  77268.  
  77269. Constants
  77270.  
  77271. ; SFPutFile dialog template ID
  77272.  
  77273. putDlgID    .EQU    -3999
  77274.  
  77275. ; Item numbers of enabled items in SFPutFile dialog
  77276.  
  77277. putSave     .EQU    1    ;Save button
  77278. putCancel   .EQU    2    ;Cancel button
  77279. putEject    .EQU    5    ;Eject button
  77280. putDrive    .EQU    6    ;Drive button
  77281. putName     .EQU    7    ;editText item for file name
  77282.  
  77283. ; SFGetFile dialog template ID
  77284.  
  77285. getDlgID    .EQU    -4000
  77286.  
  77287. ; Item numbers of enabled items in SFGetFile dialog
  77288.  
  77289. getOpen     .EQU    1    ;Open button
  77290. getCancel   .EQU    3    ;Cancel button
  77291. getEject    .EQU    5    ;Eject button
  77292. getDrive    .EQU    6    ;Drive button
  77293. getNmList   .EQU    7    ;userItem for file name list
  77294. getScroll   .EQU    8    ;userItem for scroll bar
  77295.  
  77296. ; Routine selectors
  77297.  
  77298. sfPutFile   .EQU    1
  77299. sfGetFile   .EQU    2
  77300. sfPPutFile  .EQU    3
  77301. sfPGetFile  .EQU    4
  77302.  
  77303. Reply Record Data Structure
  77304.  
  77305. rGood       0 if ignore command (byte)
  77306. rType       File type (long)
  77307. rVolume     Volume reference number (word)
  77308. rVersion    File’s version number (word)
  77309. rName       File name (length byte followed by up to 63 characters)
  77310.  
  77311. Trap Macro Name
  77312.  
  77313. _Pack3
  77314.  
  77315. Variables
  77316.  
  77317. SFSaveDisk    Negative of volume reference number used by
  77318.               Standard File Package (word)
  77319. CurDirStore   Directory ID of directory last opened (long)
  77320. SFSaveDisk    Negative of volume reference number (word)
  77321.  
  77322. æKY SFPGetFile
  77323. æFc StandardFile.h
  77324. æT Function
  77325. æTN A9EA
  77326. æD pascal void SFPGetFile(Point where,const Str255 prompt,FileFilterProcPtr fileFilter,
  77327.     short numTypes,SFTypeList typeList,DlgHookProcPtr dlgHook,SFReply *reply,
  77328.     short dlgID,ModalFilterProcPtr filterProc)
  77329.     = {0x3F3C,0x0004,0xA9EA}; 
  77330. æDT SFPGetFile((Point) where,(const Str255) prompt,(FileFilterProcPtr) fileFilter,()
  77331.     short numTypes,(SFTypeList) typeList,(DlgHookProcPtr) dlgHook,(SFReply *) reply,()
  77332.     short dlgID,(ModalFilterProcPtr) filterProc);
  77333. æC 
  77334. SFPGetFile is an alternative to SFGetFile for advanced programmers who want to use a
  77335. nonstandard dialog box. It’s the same as SFGetFile except for the two additional
  77336. parameters dlgID and filterProc.
  77337.  
  77338. DlgID is the resource ID of the dialog template to be used instead of the standard
  77339. one (so you can use whatever ID you wish rather than the same one as the standard).
  77340.  
  77341. The filterProc parameter determines how ModalDialog will filter events when called by
  77342. SFPGetFile. If filterProc is NIL, ModalDialog does the standard filtering that it
  77343. does when called by SFGetFile; otherwise, filterProc should point to a function for
  77344. ModalDialog to execute after doing the standard filtering. The function must be the
  77345. same as one you would pass directly to ModalDialog in its filterProc parameter. (See
  77346. the Dialog Manager chapter for more information.) Note that the standard filtering
  77347. will detect key-down events only if the dialog template ID is the standard one.
  77348.  Assembly-Language Information
  77349.  
  77350. Constants
  77351.  
  77352. ; SFPutFile dialog template ID
  77353.  
  77354. putDlgID    .EQU    -3999
  77355.  
  77356. ; Item numbers of enabled items in SFPutFile dialog
  77357.  
  77358. putSave     .EQU    1    ;Save button
  77359. putCancel   .EQU    2    ;Cancel button
  77360. putEject    .EQU    5    ;Eject button
  77361. putDrive    .EQU    6    ;Drive button
  77362. putName     .EQU    7    ;editText item for file name
  77363.  
  77364. ; SFGetFile dialog template ID
  77365.  
  77366. getDlgID    .EQU    -4000
  77367.  
  77368. ; Item numbers of enabled items in SFGetFile dialog
  77369.  
  77370. getOpen     .EQU    1    ;Open button
  77371. getCancel   .EQU    3    ;Cancel button
  77372. getEject    .EQU    5    ;Eject button
  77373. getDrive    .EQU    6    ;Drive button
  77374. getNmList   .EQU    7    ;userItem for file name list
  77375. getScroll   .EQU    8    ;userItem for scroll bar
  77376.  
  77377. ; Routine selectors
  77378.  
  77379. sfPutFile   .EQU    1
  77380. sfGetFile   .EQU    2
  77381. sfPPutFile  .EQU    3
  77382. sfPGetFile  .EQU    4
  77383.  
  77384. Reply Record Data Structure
  77385.  
  77386. rGood       0 if ignore command (byte)
  77387. rType       File type (long)
  77388. rVolume     Volume reference number (word)
  77389. rVersion    File’s version number (word)
  77390. rName       File name (length byte followed by up to 63 characters)
  77391.  
  77392. Trap Macro Name
  77393.  
  77394. _Pack3
  77395.  
  77396. Variables
  77397.  
  77398. SFSaveDisk    Negative of volume reference number used by
  77399.               Standard File Package (word)
  77400. CurDirStore   Directory ID of directory last opened (long)
  77401. SFSaveDisk    Negative of volume reference number (word)
  77402.  
  77403.  
  77404. æKY StandardPutFile
  77405. æFc StandardFile.h
  77406. æT Function
  77407. æTN A9EA
  77408. æD pascal void StandardPutFile(const Str255 prompt,const Str255 defaultName,
  77409.     StandardFileReply *reply)
  77410.     = {0x3F3C,0x0005,0xA9EA}; 
  77411. æDT StandardPutFile((const Str255) prompt,(const Str255) defaultName,(
  77412.     StandardFileReply) * reply);
  77413. æC 
  77414.  
  77415. æKY StandardGetFile
  77416. æFc StandardFile.h
  77417. æT Function
  77418. æTN A9EA
  77419. æD pascal void StandardGetFile(const Str255 prompt,FileFilterProcPtr fileFilter,
  77420.     short numTypes,SFTypeList typeList,StandardFileReply *reply)
  77421.     = {0x3F3C,0x0006,0xA9EA}; 
  77422. æDT StandardGetFile((const Str255) prompt,(FileFilterProcPtr) fileFilter,()
  77423.     short numTypes,(SFTypeList) typeList,(StandardFileReply *) reply);
  77424. æC 
  77425.  
  77426. æKY CustomPutFile
  77427. æFc StandardFile.h
  77428. æT Function
  77429. æTN A9EA
  77430. æD pascal void CustomPutFile(const Str255 prompt,const Str255 defaultName,
  77431.     StandardFileReply *reply,short dlgID,Point where,DlgHookCBProcPtr dlgHook,
  77432.     ModalFilterCBProcPtr filterProc,short *activeList,ActivateCBProcPtr activateProc,
  77433.     void *callBackPtr)
  77434.     = {0x3F3C,0x0007,0xA9EA}; 
  77435. æDT CustomPutFile((const Str255) prompt,(const Str255) defaultName,(
  77436.     StandardFileReply) * reply,(short) dlgID,(Point) where,(DlgHookCBProcPtr) dlgHook,()
  77437.     ModalFilterCBProcPtr filterProc,(short *) activeList,(ActivateCBProcPtr) activateProc,(
  77438.     void) * callBackPtr);
  77439. æC 
  77440.  
  77441. æKY CustomGetFile
  77442. æFc StandardFile.h
  77443. æT Function
  77444. æTN A9EA
  77445. æD pascal void CustomGetFile(FileFilterCBProcPtr fileFilter,short numTypes,
  77446.     SFTypeList typeList,StandardFileReply *reply,short dlgID,Point where,DlgHookCBProcPtr dlgHook,
  77447.     ModalFilterCBProcPtr filterProc,short *activeList,ActivateCBProcPtr activateProc,
  77448.     void *callBackPtr)
  77449.     = {0x3F3C,0x0008,0xA9EA}; 
  77450. /* 
  77451.      New StandardFile comments:
  77452.      
  77453.      activeList is pointer to array of integer (16-bits).
  77454.      first integer is length of list.
  77455.      following integers are possible activatable DITL items, in 
  77456.      the order that the tab key will cycle through.  The first
  77457.      in the list is the item made active when dialog is first shown.
  77458.     
  77459.      activateProc is a pointer to a procedure like:
  77460.         PROCEDURE MyActivateProc(theDialog:     DialogPtr; 
  77461.                                     itemNo:     INTEGER; 
  77462.                                     activating: BOOLEAN;
  77463.                                     callBackPtr:Ptr); 
  77464.      The activateProc is called with activating=FALSE on the itemNo
  77465.      about to deactivate then with activating=TRUE on the itemNo
  77466.      about to become the active item. (like activate event)
  77467.     
  77468.      callBackPtr is a nice little extra that makes life easier without
  77469.      globals.  CustomGetFile & CustomPPutFile when calling any of their
  77470.      call back procedures, pushes the extra parameter of callBackPtr on
  77471.      the stack.  
  77472.      
  77473.      In addition the filterProc in CustomGetFile & CustomPPutFile is called
  77474.      before before SF does any mapping, instead of after.
  77475. */
  77476.  
  77477. æDT CustomGetFile((FileFilterCBProcPtr) fileFilter,(short) numTypes,()
  77478.     SFTypeList typeList,(StandardFileReply *) reply,(short) dlgID,(Point) where,(DlgHookCBProcPtr) dlgHook,()
  77479.     ModalFilterCBProcPtr filterProc,(short *) activeList,(ActivateCBProcPtr) activateProc,(
  77480.     void) * callBackPtr);
  77481. æC 
  77482.  
  77483.  
  77484. æKY Start.h
  77485. æKL GetDefaultStartup
  77486. GetOSDefault
  77487. GetTimeout
  77488. GetVideoDefault
  77489. SetDefaultStartup
  77490. SetOSDefault
  77491. SetTimeout
  77492. SetVideoDefault
  77493.  
  77494. DefOSPtr
  77495. DefOSRec
  77496. DefStartPtr
  77497. DefStartRec
  77498. DefVideoPtr
  77499. DefVideoRec
  77500. SCSIDev
  77501. SlotDev
  77502.  
  77503. æKY SlotDev
  77504. æFc Start.h
  77505. æT struct
  77506. æD struct SlotDev {
  77507.     char sdExtDevID;
  77508.     char sdPartition;
  77509.     char sdSlotNum;
  77510.     char sdSRsrcID;
  77511. };
  77512.  
  77513. typedef struct SlotDev SlotDev;
  77514. æC 
  77515.  
  77516. æKY SCSIDev
  77517. æFc Start.h
  77518. æT struct
  77519. æD struct SCSIDev {
  77520.     char sdReserved1;
  77521.     char sdReserved2;
  77522.     short sdRefNum;
  77523. };
  77524.  
  77525. typedef struct SCSIDev SCSIDev;
  77526. æC 
  77527.  
  77528. æKY DefStartRec
  77529. DefStartPtr
  77530. æFc Start.h
  77531. æT struct
  77532. æD union DefStartRec {
  77533.     SlotDev slotDev;
  77534.     SCSIDev scsiDev;
  77535. };
  77536.  
  77537. typedef union DefStartRec DefStartRec;
  77538.  
  77539. typedef DefStartRec *DefStartPtr;
  77540.  
  77541. æC 
  77542. The routines described below are used by the Start Manager for configuring the system
  77543. startup process.  Only a very few advanced programmers who wish to implement a different
  77544. operating system on the Macintosh will ever need to use these routines.
  77545.  
  77546. GetDefaultStartup, SetDefaultStartup, GetTimeout, and Set Timeout are implemented for
  77547. both the Macintosh SE and the Macintosh II.  GetVideoDefault, SetVideoDefault, GetOSDefault,
  77548. and SetOSDefault are implemented only on the Macintosh II.
  77549.  
  77550. Routine parameters for GetDefaultStartup, SetDefaultStartup, GetVideoDefault, SetVideoDefault,
  77551. GetOSDefault, and SetOSDefault are passed and returned using parameter blocks.
  77552.  
  77553. Assembly-language note:  When you call GetDefaultStartup, SetDefaultStartup,
  77554.                          GetVideoDefault, SetVideoDefault, GetOSDefault, and
  77555.                          SetOSDefault, A0 must point to a parameter block that
  77556.                          will contain the parameters passed to, or returned
  77557.                          by, the routine.
  77558.  
  77559. The DefStartRec parameter block used by GetDefaultStartup and SetDefaultStartup has
  77560. the following structure:
  77561.  
  77562. TYPE  DefStartType = (slotDev,scsiDev);
  77563.       DefStartRec  =  RECORD
  77564.                         CASE DefStartType OF
  77565.                          slotDev:
  77566.                           sdExtDevID:   SignedByte;  {external device ID}
  77567.                           sdPartition:  SignedByte;  {reserved}
  77568.                           sdSlotNum:    SignedByte;  {slot number}
  77569.                           sdSRsrcID:    SignedByte;  {SResourceID}
  77570.                          scsiDev:
  77571.                           sdReserved1:  SignedByte;  {reserved}
  77572.                           sdReserved2:  SignedByte;  {reserved}
  77573.                           sdRefNum:     INTEGER      {driver reference number}
  77574.                       END;
  77575.  
  77576.       DefStartPtr  = ^DefStartRec
  77577.  
  77578. The two variants of the StartDevPBRec correspond to two types of devices that can
  77579. currently be connected.  The slotDev variant contains information about slot devices,
  77580. while the scsiDev variant describes a device connected through the SCSI port.
  77581.  
  77582. æKY DefVideoRec
  77583. DefVideoPtr
  77584. æFc Start.h
  77585. æT struct
  77586. æD struct DefVideoRec {
  77587.     char sdSlot;
  77588.     char sdsResource;
  77589. };
  77590.  
  77591. typedef struct DefVideoRec DefVideoRec;
  77592. typedef DefVideoRec *DefVideoPtr;
  77593.  
  77594. æC 
  77595.  
  77596. æKY DefOSRec
  77597. DefOSPtr
  77598. æFc Start.h
  77599. æT struct
  77600. æD struct DefOSRec {
  77601.     char sdReserved;
  77602.     char sdOSType;
  77603. };
  77604.  
  77605. typedef struct DefOSRec DefOSRec;
  77606. typedef DefOSRec *DefOSPtr;
  77607.  
  77608. æC 
  77609.  
  77610. æKY GetDefaultStartup
  77611. æFc Start.h
  77612. æT Function
  77613. æD pascal void GetDefaultStartup(DefStartPtr paramBlock); 
  77614. æDT GetDefaultStartup((DefStartPtr) paramBlock);
  77615. æRI V-353
  77616. æC 
  77617. The routines described below are used by the Start Manager for configuring the system
  77618. startup process.  Only a very few advanced programmers who wish to implement a different
  77619. operating system on the Macintosh will ever need to use these routines.
  77620.  
  77621. GetDefaultStartup, SetDefaultStartup, GetTimeout, and Set Timeout are implemented for
  77622. both the Macintosh SE and the Macintosh II.  GetVideoDefault, SetVideoDefault, GetOSDefault,
  77623. and SetOSDefault are implemented only on the Macintosh II.
  77624.  
  77625. Routine parameters for GetDefaultStartup, SetDefaultStartup, GetVideoDefault, SetVideoDefault,
  77626. GetOSDefault, and SetOSDefault are passed and returned using parameter blocks.
  77627.  
  77628. Assembly-language note:  When you call GetDefaultStartup, SetDefaultStartup,
  77629.                          GetVideoDefault, SetVideoDefault, GetOSDefault, and
  77630.                          SetOSDefault, A0 must point to a parameter block that
  77631.                          will contain the parameters passed to, or returned
  77632.                          by, the routine.
  77633.  
  77634. PROCEDURE GetDefaultStartup (paramBlock: DefStartPtr);
  77635.  
  77636.   -->    0    sdExtDevID   byte    or    -->    0    sdReserved1  byte
  77637.   -->    1    sdPartition  byte          -->    1    sdReserved2  byte
  77638.   -->    2    sdSlotNum    byte          -->    2    sdRefNum     word
  77639.   -->    3    sdSRsrcID    byte
  77640.  
  77641. GetDefaultStartup returns information about the default startup device from parameter
  77642. RAM.  To determine which variant to use, you need to look at the sdRefNum field.  If
  77643. this field contains a negative number, it’s the driver reference number for an SCSI
  77644. device, which is all you need to know.
  77645. (SDReserved1 and sdReserved2 are reserved for future use.)
  77646.  
  77647. If sdRefNum contains a positive number, you’ll need to access the information in the
  77648. slotDev variant.  SDExtDevID is specified by a slot’s driver; it identifies one of
  77649. perhaps several devices that are connected through a single slot.  SDSlotNum is the
  77650. slot number  ($9 thru E) and sdSRsrcID is the sResource ID; see the Slot Manager
  77651. chapter for details.
  77652.  
  77653. æKY SetDefaultStartup
  77654. æFc Start.h
  77655. æT Function
  77656. æD pascal void SetDefaultStartup(DefStartPtr paramBlock); 
  77657. æDT SetDefaultStartup((DefStartPtr) paramBlock);
  77658. æRI V-354
  77659. æC 
  77660. The routines described below are used by the Start Manager for configuring the system
  77661. startup process.  Only a very few advanced programmers who wish to implement a different
  77662. operating system on the Macintosh will ever need to use these routines.
  77663.  
  77664. GetDefaultStartup, SetDefaultStartup, GetTimeout, and Set Timeout are implemented for
  77665. both the Macintosh SE and the Macintosh II.  GetVideoDefault, SetVideoDefault, GetOSDefault,
  77666. and SetOSDefault are implemented only on the Macintosh II.
  77667.  
  77668. Routine parameters for GetDefaultStartup, SetDefaultStartup, GetVideoDefault, SetVideoDefault,
  77669. GetOSDefault, and SetOSDefault are passed and returned using parameter blocks.
  77670.  
  77671. Assembly-language note:  When you call GetDefaultStartup, SetDefaultStartup,
  77672.                          GetVideoDefault, SetVideoDefault, GetOSDefault, and
  77673.                          SetOSDefault, A0 must point to a parameter block that
  77674.                          will contain the parameters passed to, or returned
  77675.                          by, the routine.
  77676.  
  77677. PROCEDURE SetDefaultStartup (paramBlock: DefStartPtr);
  77678.  
  77679.   <--    0    sdExtDevID   byte    or    <--    0    sdReserved1  byte
  77680.   <--    1    sdPartition  byte          <--    1    sdReserved2  byte
  77681.   <--    2    sdSlotNum    byte          <--    2    sdRefNum     word
  77682.   <--    3    sdSRsrcID    byte
  77683.  
  77684. SetDefaultStartup specifies a device as the default startup device.  For a slot
  77685. device, sdExtDevID (specified by the slot’s driver) identifies one of perhaps several
  77686. devices that are connected through a single slot.  SDSlotNum is the slot number  ($9
  77687. thru E) and sdSRsrcID is the sResource ID; see the Slot Manager chapter for details.
  77688.  
  77689. In the case of an SCSI device, sdRefNum contains the reference number; to specify no
  77690. device as default (meaning that the first available device will be chosen at startup),
  77691. pass 0 in sdRefNum.  SDReserved1 and sdReserved2 are reserved for future use and
  77692. should be 0.
  77693.  
  77694. The GetVideoDefault and SetVideoDefault calls use the following parameter block to
  77695. pass information about the default video device:
  77696.  
  77697. TYPE  DefVideoRec = RECORD
  77698.                       sdSlot:       SignedByte;    {slot number}
  77699.                       sdSResource:  SignedByte;    {sResource ID}
  77700.                     END;
  77701.  
  77702.       DefVideoPtr = ^DefVideoRec
  77703.  
  77704. æKY GetVideoDefault
  77705. æFc Start.h
  77706. æT Function
  77707. æD pascal void GetVideoDefault(DefVideoPtr paramBlock); 
  77708. æDT GetVideoDefault((DefVideoPtr) paramBlock);
  77709. æRI V-354
  77710. æC 
  77711. The routines described below are used by the Start Manager for configuring the system
  77712. startup process.  Only a very few advanced programmers who wish to implement a different
  77713. operating system on the Macintosh will ever need to use these routines.
  77714.  
  77715. GetDefaultStartup, SetDefaultStartup, GetTimeout, and Set Timeout are implemented for
  77716. both the Macintosh SE and the Macintosh II.  GetVideoDefault, SetVideoDefault, GetOSDefault,
  77717. and SetOSDefault are implemented only on the Macintosh II.
  77718.  
  77719. Routine parameters for GetDefaultStartup, SetDefaultStartup, GetVideoDefault, SetVideoDefault,
  77720. GetOSDefault, and SetOSDefault are passed and returned using parameter blocks.
  77721.  
  77722. Assembly-language note:  When you call GetDefaultStartup, SetDefaultStartup,
  77723.                          GetVideoDefault, SetVideoDefault, GetOSDefault, and
  77724.                          SetOSDefault, A0 must point to a parameter block that
  77725.                          will contain the parameters passed to, or returned
  77726.                          by, the routine.
  77727.  
  77728. Trap macro  _GetVideoDefault
  77729.  
  77730. Parameter block
  77731.   -->    0    sdSlot       byte
  77732.   -->    1    sdSResource  byte
  77733.  
  77734. GetVideoDefault returns the slot number and sResourceID of the default video device. 
  77735. If sdSlot returns 0, there is no default video device and the first available video
  77736. device will be chosen.
  77737.  
  77738. æKY SetVideoDefault
  77739. æFc Start.h
  77740. æT Function
  77741. æD pascal void SetVideoDefault(DefVideoPtr paramBlock); 
  77742. æDT SetVideoDefault((DefVideoPtr) paramBlock);
  77743. æRI V-355
  77744. æC 
  77745. The routines described below are used by the Start Manager for configuring the system
  77746. startup process.  Only a very few advanced programmers who wish to implement a different
  77747. operating system on the Macintosh will ever need to use these routines.
  77748.  
  77749. GetDefaultStartup, SetDefaultStartup, GetTimeout, and Set Timeout are implemented for
  77750. both the Macintosh SE and the Macintosh II.  GetVideoDefault, SetVideoDefault, GetOSDefault,
  77751. and SetOSDefault are implemented only on the Macintosh II.
  77752.  
  77753. Routine parameters for GetDefaultStartup, SetDefaultStartup, GetVideoDefault, SetVideoDefault,
  77754. GetOSDefault, and SetOSDefault are passed and returned using parameter blocks.
  77755.  
  77756. Assembly-language note:  When you call GetDefaultStartup, SetDefaultStartup,
  77757.                          GetVideoDefault, SetVideoDefault, GetOSDefault, and
  77758.                          SetOSDefault, A0 must point to a parameter block that
  77759.                          will contain the parameters passed to, or returned
  77760.                          by, the routine.
  77761.  
  77762. Trap macro  _SetVideoDefault
  77763.  
  77764. Parameter block
  77765.   <--    0    sdSlot       byte
  77766.   <--    1    sdSResource  byte
  77767.  
  77768. SetVideoDefault makes the device with the given slot number and sResourceID the
  77769. default video device.
  77770.  
  77771. The GetOSDefault and SetOSDefault calls use the following parameter block to pas
  77772. information about the default operating system:
  77773.  
  77774. TYPE  DefOSRec = RECORD
  77775.                    sdReserved:  SignedByte;  {reserved--should be 0}
  77776.                    sdOSType:    SignedByte;  {operating system type}
  77777.                  END;
  77778.  
  77779.       DefOSPtr = ^DefOSRec
  77780.  
  77781. æKY GetOSDefault
  77782. æFc Start.h
  77783. æT Function
  77784. æD pascal void GetOSDefault(DefOSPtr paramBlock); 
  77785. æDT GetOSDefault((DefOSPtr) paramBlock);
  77786. æRI V-355
  77787. æC 
  77788. The routines described below are used by the Start Manager for configuring the system
  77789. startup process.  Only a very few advanced programmers who wish to implement a different
  77790. operating system on the Macintosh will ever need to use these routines.
  77791.  
  77792. GetDefaultStartup, SetDefaultStartup, GetTimeout, and Set Timeout are implemented for
  77793. both the Macintosh SE and the Macintosh II.  GetVideoDefault, SetVideoDefault, GetOSDefault,
  77794. and SetOSDefault are implemented only on the Macintosh II.
  77795.  
  77796. Routine parameters for GetDefaultStartup, SetDefaultStartup, GetVideoDefault, SetVideoDefault,
  77797. GetOSDefault, and SetOSDefault are passed and returned using parameter blocks.
  77798.  
  77799. Assembly-language note:  When you call GetDefaultStartup, SetDefaultStartup,
  77800.                          GetVideoDefault, SetVideoDefault, GetOSDefault, and
  77801.                          SetOSDefault, A0 must point to a parameter block that
  77802.                          will contain the parameters passed to, or returned
  77803.                          by, the routine.
  77804.  
  77805. Trap macro  _GetOSDefault
  77806.  
  77807. Parameter block
  77808.   -->    0    sdReserved  byte
  77809.   -->    1    sdOSType    byte
  77810.  
  77811. GetOSDefault returns a value in sdOSType identifying the operating system to be used
  77812. at startup.  The sdReserved parameter currently returns 0; it’s reserved for future
  77813. use.  This call is generally used only with partitioned devices containing multiple
  77814. operating systems; for more details, see the SCSI Manager chapter.
  77815.  
  77816. æKY SetOSDefault
  77817. æFc Start.h
  77818. æT Function
  77819. æD pascal void SetOSDefault(DefOSPtr paramBlock); 
  77820. æDT SetOSDefault((DefOSPtr) paramBlock);
  77821. æRI V-355
  77822. æC 
  77823. The routines described below are used by the Start Manager for configuring the system
  77824. startup process.  Only a very few advanced programmers who wish to implement a different
  77825. operating system on the Macintosh will ever need to use these routines.
  77826.  
  77827. GetDefaultStartup, SetDefaultStartup, GetTimeout, and Set Timeout are implemented for
  77828. both the Macintosh SE and the Macintosh II.  GetVideoDefault, SetVideoDefault, GetOSDefault,
  77829. and SetOSDefault are implemented only on the Macintosh II.
  77830.  
  77831. Routine parameters for GetDefaultStartup, SetDefaultStartup, GetVideoDefault, SetVideoDefault,
  77832. GetOSDefault, and SetOSDefault are passed and returned using parameter blocks.
  77833.  
  77834. Assembly-language note:  When you call GetDefaultStartup, SetDefaultStartup,
  77835.                          GetVideoDefault, SetVideoDefault, GetOSDefault, and
  77836.                          SetOSDefault, A0 must point to a parameter block that
  77837.                          will contain the parameters passed to, or returned
  77838.                          by, the routine.
  77839.  
  77840. Trap macro  _SetOSDefault
  77841.  
  77842. Parameter block
  77843.   <--    0    sdReserved  byte
  77844.   <--    1    sdOSType    byte
  77845.  
  77846. SetOSDefault specifies in sdOSType the operating system to be used at startup.  The
  77847. sdReserved parameter is reserved for future use and should be 0.  This call is generally
  77848. used only with partitioned devices containing multiple operating systems; for details,
  77849. see the SCSI Manager chapter.
  77850.  
  77851. æKY SetTimeout
  77852. æFc Start.h
  77853. æT Function
  77854. æD pascal void SetTimeout(short count); 
  77855. æDT SetTimeout((short) count);
  77856. æRI V-356
  77857. æC 
  77858. The routines described below are used by the Start Manager for configuring the system
  77859. startup process.  Only a very few advanced programmers who wish to implement a different
  77860. operating system on the Macintosh will ever need to use these routines.
  77861.  
  77862. GetDefaultStartup, SetDefaultStartup, GetTimeout, and Set Timeout are implemented for
  77863. both the Macintosh SE and the Macintosh II.  GetVideoDefault, SetVideoDefault, GetOSDefault,
  77864. and SetOSDefault are implemented only on the Macintosh II.
  77865.  
  77866. Routine parameters for GetDefaultStartup, SetDefaultStartup, GetVideoDefault, SetVideoDefault,
  77867. GetOSDefault, and SetOSDefault are passed and returned using parameter blocks.
  77868.  
  77869. Assembly-language note:  When you call GetDefaultStartup, SetDefaultStartup,
  77870.                          GetVideoDefault, SetVideoDefault, GetOSDefault, and
  77871.                          SetOSDefault, A0 must point to a parameter block that
  77872.                          will contain the parameters passed to, or returned
  77873.                          by, the routine.
  77874.  
  77875.  
  77876. Trap macro  _SetTimeout
  77877. On entry    D0:  count (word)
  77878.  
  77879. Note:  The _SetTimeout macro is actually not a trap, but expands to invoke
  77880.        the trap macro _InternalWait with a routine selector of 1 pushed on
  77881.        the stack.
  77882.  
  77883. SetTimeout lets you specify in count the number of seconds the system should wait for
  77884. the internal hard disk to respond.  The maximum value is 31 seconds; a value of 0
  77885. indicates the default timeout of 15 seconds.
  77886.  
  77887. æKY GetTimeout
  77888. æFc Start.h
  77889. æT Function
  77890. æD pascal void GetTimeout(short *count); 
  77891. æDT GetTimeout((short *) count);
  77892. æRI V-356
  77893. æC 
  77894. The routines described below are used by the Start Manager for configuring the system
  77895. startup process.  Only a very few advanced programmers who wish to implement a different
  77896. operating system on the Macintosh will ever need to use these routines.
  77897.  
  77898. GetDefaultStartup, SetDefaultStartup, GetTimeout, and Set Timeout are implemented for
  77899. both the Macintosh SE and the Macintosh II.  GetVideoDefault, SetVideoDefault, GetOSDefault,
  77900. and SetOSDefault are implemented only on the Macintosh II.
  77901.  
  77902. Routine parameters for GetDefaultStartup, SetDefaultStartup, GetVideoDefault, SetVideoDefault,
  77903. GetOSDefault, and SetOSDefault are passed and returned using parameter blocks.
  77904.  
  77905. Assembly-language note:  When you call GetDefaultStartup, SetDefaultStartup,
  77906.                          GetVideoDefault, SetVideoDefault, GetOSDefault, and
  77907.                          SetOSDefault, A0 must point to a parameter block that
  77908.                          will contain the parameters passed to, or returned
  77909.                          by, the routine.
  77910.  
  77911. Trap macro  _GetTimeout
  77912. On exit     D0:  count (word)
  77913.  
  77914. Note:  The _GetTimeout macro is actually not a trap, but expands to invoke
  77915.        the trap macro _InternalWait with a routine selector of 0 pushed on
  77916.        the stack.
  77917.  
  77918. GetTimeout returns in count the number of seconds the system will wait for the internal
  77919. hard disk to respond.  A value of 0 indicates the default timeout of 15 seconds.
  77920.  
  77921.  
  77922. æKY StdArg.h
  77923. æFc StdArg.h
  77924. æC                           Synopsis
  77925.  
  77926. #include <StdArg.h>
  77927. typedef char *va_list;   /*character pointer */
  77928. #define va_start(va_list ap, parmN) 
  77929. #define va_arg(va_list ap, type) 
  77930. #define va_end(va_list ap)   /* do nothing */
  77931.  
  77932.                            Description
  77933.  
  77934. The va_start; macro initializes a list of arguments for later 
  77935. use by the va_arg and va_end macros. The va_start macro takes 
  77936. two arguments: the variable list ap used to refer to the optional 
  77937. arguments, and the name of the last named argument parmN 
  77938. passed to the function. It returns no value.
  77939. The va_arg macro; returns a value for each of the optional 
  77940. arguments contained in the va_list initialized by va_start. 
  77941. Successive uses of va_arg return both the current position and 
  77942. the type of each of the arguments in va_list.
  77943. The va_end; macro does any necessary cleanup after using 
  77944. optional arguments with va_arg. It returns no value, but simply 
  77945. allows a normal return from va_arg.
  77946.  
  77947. Example
  77948. For a sample function declaration taking two or more arguments:
  77949. #include <StdArg.h>
  77950. /* ANSI function declarations use ', ...'to indicate
  77951.  the position of the first optional argument.*/ 
  77952.      .
  77953. int foo(char *arg1, int arg2, ...);
  77954.  {
  77955.  va_list nextArg;            /* A local variable, nextArg,
  77956.                                  indicates the current position in the
  77957.                                  list of optional arguments */
  77958.  va_start(nextArg, arg2);    /* set up va_list */
  77959.  va_arg(nextArg, int);       /* refer to each optional argument in turn */
  77960.      .
  77961.      .
  77962.      .
  77963.  va_end(nextArg);            /* cleanup after va_arg */
  77964.  }
  77965.  
  77966. Since the compiler widens many argument types when they are pushed 
  77967. on the stack, it is important to remember that the argument type in 
  77968. va_arg should represent the type whose length corresponds to the 
  77969. length of the argument on the stack. Here are some examples.
  77970.  
  77971. Type     Type pushed on stack
  77972.  
  77973. float    extended
  77974. double   extended
  77975. char     int
  77976. short    int
  77977.  
  77978.                            Note
  77979.  
  77980. The StdArg.h header file was named VarArg.h in previous 
  77981. versions of MPW C.
  77982.  
  77983. See also
  77984. Formatted input/output
  77985.  
  77986.  
  77987. æKY StdCLib
  77988. æKL Assert.h
  77989. Ctype.h
  77990. Errno.h
  77991. FCntl.h
  77992. Float.h
  77993. IOCtl.h
  77994. Limits.h
  77995. Locale.h
  77996. Math.h
  77997. SetJmp.h
  77998. Signal.h
  77999. StdArg.h
  78000. StdDef.h
  78001. StdIO.h
  78002. StdLib.h
  78003. String.h
  78004. Time.h
  78005.  
  78006. abort
  78007. abs
  78008. acos
  78009. asctime
  78010. asin
  78011. assert
  78012. atan
  78013. atan2
  78014. atexit
  78015. atof
  78016. atoi
  78017. atol
  78018. bsearch
  78019. calloc
  78020. ceil
  78021. clearerr
  78022. clock
  78023. close
  78024. cos
  78025. cosh
  78026. create
  78027. ctime
  78028. difftime
  78029. div
  78030. dup
  78031. ecvt
  78032. exit
  78033. exp
  78034. fabs
  78035. faccess
  78036. fclose
  78037. fcntl
  78038. fcvt 
  78039. fdopen
  78040. feof
  78041. ferror
  78042. fflush
  78043. fgetc
  78044. fgetpos
  78045. fgets
  78046. fileno
  78047. floor
  78048. fmod
  78049. fopen
  78050. fprintf
  78051. fputc
  78052. fputs
  78053. fread
  78054. free
  78055. freopen
  78056. frexp 
  78057. fscanf
  78058. fseek
  78059. fsetpos
  78060. ftell
  78061. fwrite
  78062. getc
  78063. getchar
  78064. getenv
  78065. gets
  78066. getw
  78067. gmtime
  78068. hypot
  78069. isalnum
  78070. isalpha
  78071. isascii
  78072. iscntrl
  78073. isdigit
  78074. isgraph
  78075. islower
  78076. isprint
  78077. ispunct
  78078. isspace
  78079. isupper
  78080. isxdigit
  78081. labs
  78082. ldexp
  78083. ldiv
  78084. localeconv
  78085. localtime
  78086. log
  78087. log10
  78088. longjmp
  78089. lseek 
  78090. malloc
  78091. mblen
  78092. mbtowc
  78093. mbstowcs
  78094. memccpy
  78095. memchr
  78096. memcmp
  78097. memcpy
  78098. memmove
  78099. memset
  78100. mktime
  78101. modf
  78102. open
  78103. perror
  78104. pow
  78105. printf
  78106. putc
  78107. putchar
  78108. puts
  78109. putw
  78110. qsort
  78111. raise
  78112. rand
  78113. read
  78114. realloc
  78115. remove
  78116. rename
  78117. rewind
  78118. scanf
  78119. setbuf
  78120. setlocale
  78121. setvbuf
  78122. signal
  78123. sin
  78124. sinh
  78125. sprintf
  78126. sqrt
  78127. sscanf
  78128. srand
  78129. strcat
  78130. strchr
  78131. strcmp
  78132. strcoll
  78133. strcpy
  78134. strcspn
  78135. strerror
  78136. strftime
  78137. strlen
  78138. strncat
  78139. strncmp
  78140. strncpy
  78141. strpbrk
  78142. strrchr
  78143. strspn
  78144. strstr
  78145. strtod
  78146. strtok
  78147. strtol
  78148. strtoul
  78149. strxfrm
  78150. system
  78151. tan
  78152. tanh
  78153. time
  78154. tmpfile
  78155. tmpnam
  78156. toascii
  78157. tolower
  78158. toupper
  78159. ungetc
  78160. unlink
  78161. vfprintf
  78162. vprintf
  78163. vsprintf
  78164. wctomb
  78165. wcstombs
  78166. write
  78167. _toupper
  78168. _tolower
  78169.  
  78170.  
  78171. æKY StdDef.h
  78172. æFc StdDef.h
  78173.  
  78174. æC Synopsis
  78175.  
  78176. #include <StdDef.h>
  78177. #define  NULL 0
  78178. #define offsetof (structure, field)
  78179. typedef int ptrdiff_t; 
  78180. typedef unsigned int size_t; 
  78181. typedef short wchar_t; 
  78182.  
  78183.                            Description
  78184.  
  78185. The header <StdDef.h> defines macros NULL; and offsetof;, 
  78186. and types ptrdiff_t;,  size_t; and wchar_t;.  These 
  78187. macros and types may also be defined in several other header 
  78188. files that use them.
  78189.  
  78190. The offsetof macro tells where a field occurs within a 
  78191. structure. When evaluated, offsetof expands to an expression 
  78192. of type size_t, which contains the offset in bytes from the 
  78193. beginning of the structure to the designated structure member.
  78194.  
  78195.  
  78196. æKY StdIO.h
  78197. æFc StdIO.h
  78198. æC 
  78199. clearerr    fprintf    getchar    scanf
  78200. fclose      fputc      gets       setbuf
  78201. fdopen      fputs      getw       setvbuf
  78202. feof        fread      perror     sprintf
  78203. ferror      freopen    printf     sscanf
  78204. fflush      fscanf     putc       tmpfile
  78205. fgetc       fseek      putchar    tmpnam
  78206. fgetpos     fsetpos    puts       ungetc
  78207. fgets       ftell      putw       vfprintf
  78208. fileno      fwrite     remove     vprintf
  78209. fopen       getc       rewind     vsprintf
  78210.  
  78211. Synopsis
  78212.  
  78213. #include <StdIO.h>
  78214. #define size_t unsigned int
  78215. #define NULL 0
  78216.  
  78217. /* The basic data structure for a stream is the FILE.*/
  78218.  
  78219. typedef struct {
  78220.  int _cnt;
  78221.  unsigned char *_ptr;
  78222.  unsigned char *_base;
  78223.  unsigned char *_end;
  78224.  unsigned short _size;
  78225.  unsigned short _flag;
  78226.  unsigned short _file;
  78227. } FILE;
  78228.  
  78229. FILE *stdin, *stdout, *stderr;
  78230. typedef long fpos_t;
  78231.  
  78232.                            Description
  78233.  
  78234. input/output:buffering:MPW C stdio;The 
  78235. buffering:stdio;Standard I/O package stdio;constitutes an 
  78236. efficient user-level I/O buffering scheme. The inline macros 
  78237. getc and putc handle characters quickly. 
  78238. The following macros and higher-level routines all use getc and 
  78239. putc:
  78240.  
  78241. getchar  putchar fgetc   fgets
  78242. fprintf  fputc   fputs   fread
  78243. fscanf   fwrite  gets    getw
  78244. printf   puts    putw    scanf
  78245.  
  78246. Therefore calls to these macros and functions can be freely 
  78247. intermixed.
  78248. The constants and the following functions are implemented as 
  78249. macros:
  78250.  
  78251. getc getchar putc        putchar
  78252. feof ferror  clearerr    fileno
  78253.  
  78254. Avoid redeclaration of these names.
  78255.  
  78256. Any program that uses the Standard I/O package must include 
  78257. the <StdIO.h> header file of macro definitions. The functions, 
  78258. macros, and constants used in the Standard I/O package are 
  78259. declared in the header file and need no further declaration.
  78260.  
  78261. A stream is a file with associated buffering and is declared to 
  78262. be a pointer to a FILE variable. The functions fopen, freopen, and 
  78263. fdopen return this pointer. The information in the FILE variable 
  78264. includes
  78265.  the file access—read or write
  78266.  the file descriptor as returned by open, creat, dup, or fcntl
  78267.  the buffer size and location
  78268.  the buffer style (unbuffered, line buffered, or file buffered)
  78269.  
  78270. Standard I/O buffering
  78271.  
  78272. buffering;Output streams, with the exception of the standard 
  78273. error stream stderr, are by default file buffered if the output 
  78274. refers to a file. File stderr is by default line buffered. When an 
  78275. output stream is unbuffered, it is queued for writing on the 
  78276. destination file or window as soon as written; when it is file 
  78277. buffered, many characters are saved up and written as a block; 
  78278. when it is line buffered, each line of output is queued for 
  78279. writing as soon as the line is completed (that is, as soon as a 
  78280. newline character is written). The function setvbuf may be used 
  78281. to change the stream’s buffering strategy.
  78282. Normally, there are three open streams with constant pointers 
  78283. declared in the <StdIO.h> header file and associated with the 
  78284. standard open files;, as shown in Table 3-4:
  78285.  
  78286. Table 3-4    Standard open files
  78287.  
  78288. FILE variable    Fildes  Description             Buffer style
  78289.  
  78290. stdi             0       standard input file     file bufferedstdin;
  78291. stdout           1       standard output file    file bufferedstdout;
  78292. stderr           2       standard error file     line bufferedstderr;
  78293.  
  78294. Buffer initialization
  78295. The FILE variable returned by fopen, freopen, or fdopen has an 
  78296. initial buffer size of 0 and a NULL buffer pointer. The buffer 
  78297. size is set and the buffer allocated by a call to setbuf, setvbuf, 
  78298. or the first I/O operation on the stream, whichever comes first. 
  78299.  
  78300. Buffer initialization is done using the following algorithm:
  78301. 1.   If _IONBF (no buffering) was set by a call to setvbuf, 
  78302.      initialization steps 2 and 3 are skipped. The buffer size 
  78303.      remains 0 and the buffer pointer remains NULL.
  78304. 2.   Checks the access-mode word for _IOLBF (line buffering). 
  78305.      This bit is usually set only in the predefined FILE stderr, 
  78306.      but a call to setvbuf can set it for any file. If line buffering is 
  78307.      set, the buffer size is set to LBUFSIZ (100). If line buffering 
  78308.      is not set, ioctl is called with an FIOBUFSIZE request and the 
  78309.      buffer size is set to the returned value or to BUFSIZ (1024) if 
  78310.      no value is returned.
  78311. 3.   If the buffer pointer is NULL, a request is made for a buffer 
  78312.      whose size was determined in step 2; the buffer pointer is 
  78313.      set to point to the newly allocated buffer. If the requested 
  78314.      size cannot be allocated, attempts are made to allocate BUFSIZ 
  78315.      or LBUFSIZ if these are smaller than the requested size. If all 
  78316.      requests fail, the buffer pointer remains NULL and the _IONBF 
  78317.      (no buffering) bit is set.
  78318. 4.   Function ioctl is called with an FIOINTERACTIVE request; if it 
  78319.      returns true, the _IOSYNC bit is set in the access-mode word. 
  78320.      This is done for all FILE variables, regardless of their 
  78321.      buffering style and size. (The _IOSYNC bit is described in the 
  78322.      next section.)
  78323.  
  78324. The setvbuf function lets you specify values for buffer size, 
  78325. buffer pointer, and access-mode word other than the default 
  78326. values of 0, NULL, and 0, respectively. The setvbuf function 
  78327. must be called before the first I/O operation occurs, so that the 
  78328. buffer initialization procedure described above receives the 
  78329. values you specify instead of the default values.
  78330.  
  78331. Buffered I/O
  78332. On each write request, the bytes are transferred to the buffer 
  78333. and an internal counter is set to account for the number of 
  78334. bytes in the buffer. If _IOLBF is set and a newline character is 
  78335. encountered while transferring bytes to the buffer, the buffer 
  78336. is flushed (written immediately) and the transfer continues at 
  78337. the beginning of the buffer. This process continues until the 
  78338. write-request count is satisfied or a write error occurs.
  78339. On each read request, the _IOSYNC bit in the access-mode word 
  78340. is checked. If _IOSYNC is on, all current FILE variables that have 
  78341. _IOSYNC on and are open for writing are flushed. In other 
  78342. words, a read from an interactive FILE variable flushes all 
  78343. interactive output files before reading. This flushing ensures 
  78344. that any prompts, I/O in a window, or other visual feedback is 
  78345. displayed before the read is initiated. Then, if the internal 
  78346. counter is 0, an entire buffer is read into memory if possible. 
  78347. (For the console device, less than a buffer’s worth is likely to 
  78348. be read.) The bytes required to satisfy the read request are 
  78349. transferred, going back to the device for more if necessary, 
  78350. and an internal pointer is advanced if any bytes remain unread.
  78351.  
  78352. When the Standard I/O package is used, Standard I/O cleanup 
  78353. is performed just before termination of the application. Any 
  78354. normal return, including a call to exit, causes Standard I/O 
  78355. cleanup, which consists of a call to fclose for every open FILE 
  78356. stream.
  78357.  
  78358.                           Diagnostics
  78359.  
  78360. Most integer functions that deal with streams return the integer 
  78361. constant EOF (–1) upon reaching the end-of-file or if an error 
  78362. occurs. See the descriptions of the individual functions for 
  78363. details.
  78364.  
  78365.                            Note
  78366.  
  78367. Do not use a file descriptor (0, 1, or 2) where a FILE variable 
  78368. (stdin, stdout, or stderr) is required.
  78369. The file <StdIO.h> includes definitions other than those 
  78370. described above, but their use is not recommended.
  78371. Invalid stream pointers cause serious errors, possibly 
  78372. including program termination. Individual function 
  78373. descriptions describe the possible error conditions.
  78374. The fpos_t type can express any position in a file. A file’s end-
  78375. of-file marker has type fpos_t.
  78376.  
  78377. See also
  78378. close, exit, fclose, ferror, fopen, fread, fseek, getc, gets, lseek, 
  78379. atexit, open, printf, putc, puts, read, scanf, setbuf, ungetc, write
  78380.  
  78381. æKY fclose
  78382. fflush
  78383. æFc StdIO.h
  78384. æC                           Synopsis
  78385.  
  78386. #include <StdIO.h>
  78387. int fclose(FILE *stream);
  78388. int fflush(FILE *stream);
  78389.  
  78390.                            Description
  78391.  
  78392. The fclose; function closes a file that was opened by fopen, 
  78393. freopen, or fdopen. The function fclose causes any buffered data 
  78394. for stream to be written out, and the buffer (if one was allocated 
  78395. by the system) to be released; fclose then calls close to close 
  78396. the file descriptor associated with stream. The value of the 
  78397. parameter stream cannot be used unless reassigned with fopen, 
  78398. fdopen, or freopen.
  78399.  
  78400. The fclose function fails, returning ENOENT, if the file 
  78401. descriptor associated with stream is already closed. 
  78402. The fclose function is performed automatically for all open FILE 
  78403. streams upon calling exit.
  78404. The fflush; function causes any buffered data for stream to 
  78405. be written out; stream remains open.
  78406.  
  78407.                           Return value
  78408.  
  78409. These functions return 0 for success or –1 if an error was 
  78410. detected (such as trying to write to a file that has not been 
  78411. opened for writing).
  78412.  
  78413. See also
  78414. close, exit, fclose, fopen, setbuf, stdio
  78415.  
  78416. æKY feof
  78417. ferror
  78418. clearerr
  78419. perror
  78420. fileno
  78421. æFc StdIO.h
  78422. æC                           Synopsis
  78423.  
  78424. #include <StdIO.h>
  78425. int feof(FILE *stream);
  78426. int ferror(FILE *stream);
  78427. void clearerr(FILE *stream);
  78428. void perror (const char *s);
  78429. int fileno(FILE *stream);
  78430.  
  78431.                            Description
  78432.  
  78433. The feof; macro returns nonzero when the end-of-file has previously
  78434. been detected while reading the named input stream; otherwise, 
  78435. it returns zero.
  78436.  
  78437. The ferror; macro returns nonzero when an I/O error has previously
  78438. occurred while reading from or writing to the named stream; otherwise, 
  78439. it returns zero.
  78440. The clearerr; macro resets the error indicator and end-of-file indicator
  78441. to zero on the named stream.
  78442.  
  78443. The perror; function takes a string as its argument. If the string is 
  78444. not null, perror prints the string, plus a colon and a space. In any case,
  78445. it then prints an appropriate error message derived from the current value 
  78446. of errno. (This message is the same one that strerror would print.)
  78447.  
  78448. The fileno; macro returns the integer file descriptor associated with the
  78449. named stream, as explained in the section on the open function.
  78450.  
  78451. See also
  78452. close, fcntl, fopen, getc, gets, open, putc, puts, stdio
  78453.  
  78454. æKY fopen
  78455. freopen
  78456. fdopen
  78457. æFc StdIO.h
  78458. æC                           Synopsis
  78459.  
  78460. #include <StdIO.h>
  78461. FILE *fopen(const char *filename, const char *mode);
  78462. FILE *freopen(const char *filename, const char *mode, FILE *stream);
  78463. FILE *fdopen(int fildes, char *type);
  78464.  
  78465.                            Description
  78466.  
  78467. The fopen; function opens the file named by filename and 
  78468. associates a stream with it. 
  78469. The filename parameter points to a character string that contains 
  78470. the name of the file to be opened.
  78471. The mode parameter points to a character string beginning with 
  78472. one of the values in the first column in the following table. The 
  78473. columns “Open Mode Used” and “Description” explain how 
  78474. type is used. For more information, see open.
  78475.  
  78476. Value    Open mode used          Description
  78477.  
  78478. r        O_RDONLY                Open for reading only.
  78479. w        O_WRONLY|O_CREAT|O_TRUNC Truncate or create for writing.
  78480. a        O_WRONLY|O_APPEND       Append: open for writing at 
  78481.                                  end-of-file, or create for writing.
  78482. r+       O_RDWR                  Open for update (reading and writing).
  78483. w+       O_RDWR|O_CREAT|O_TRUNC  Truncate or create for update.
  78484. a+       O_RDWR|O_CREAT|O_APPEND Append: open or create for 
  78485.                                  update at end-of-file.
  78486.  
  78487. Binary read and write modes can also be used. These can be 
  78488. specified by using the character b in combination with any of 
  78489. the mode parameters shown above. For example, to specify 
  78490. binary read/write mode, use “rb+” or “r+b”. There is no 
  78491. difference in behavior between text streams and binary 
  78492. streams.
  78493.  
  78494. The freopen; function substitutes the named file for the open 
  78495. stream. The original stream is closed, regardless of whether 
  78496. the open ultimately succeeds. The freopen function returns a 
  78497. pointer to the FILE structure associated with stream. The freopen 
  78498. function is typically used to attach the previously opened 
  78499. streams associated with stdin, stdout, and stderr to other files.
  78500.  
  78501. The fdopen; function associates a stream with a file 
  78502. descriptor. Thus, fdopen can be used to access the file 
  78503. descriptors returned by open, creat, dup, or fcntl. (These calls 
  78504. return file descriptors, not pointers to a FILE structure.) The 
  78505. type of stream must agree with the mode of the open file.
  78506.  
  78507. When a file is opened for update, both input and output may 
  78508. be done on the resulting stream. However, output may not be 
  78509. directly followed by input without an intervening fseek or 
  78510. rewind, and input may not be directly followed by output 
  78511. without an intervening fseek, rewind, or an input operation that 
  78512. encounters end-of-file.
  78513.  
  78514. When a file is opened for append (that is, when type is a or 
  78515. a+), it is impossible to overwrite information already in the file. 
  78516. The function fseek may be used to reposition the file pointer to 
  78517. any position in the file, but when output is written to the file 
  78518. the current file pointer is disregarded. All output is written at 
  78519. the end of the file and causes the file pointer to be 
  78520. repositioned at the end of the output.
  78521.  
  78522.                            Return values
  78523.  
  78524. On success, functions fopen, freopen, and fdopen return a valid 
  78525. file pointer. On failure, NULL is returned.
  78526. The maximum number of open FILE streams is 20.
  78527.  
  78528.                            Note
  78529.  
  78530. The parameter mode must have one of the values in the first 
  78531. column in the table; do not use values intended for open, such 
  78532. as O_RDONLY.
  78533.  
  78534. See also
  78535. fclose, ferror, fread, fseek, getc, gets, open, putc, puts, setbuf, stdio
  78536.  
  78537. æKY fread
  78538. fwrite
  78539. æFc StdIO.h
  78540. æC                           Synopsis
  78541.  
  78542. #include <StdIO.h>
  78543. size_t fread(void *ptr, size_t size, size_t nmemb, FILE *stream);
  78544. int fwrite(const  void *ptr, size_t size, size_t nmemb, FILE *stream);
  78545.  
  78546.                            Description
  78547.  
  78548. The fread; function copies nmemb items of data from the named 
  78549. input stream into an array beginning at ptr. An item of data is a 
  78550. sequence of size bytes (not necessarily terminated by a null 
  78551. byte). The function fread stops appending bytes if an end-of-
  78552. file or error condition is encountered while reading stream or 
  78553. if nmemb items have been read. The function fread leaves the file 
  78554. pointer in stream pointing to the byte following the last byte 
  78555. read.
  78556.  
  78557. The fwrite; function writes at most nmemb items of data to the 
  78558. named output stream from the array pointed to by ptr. An item 
  78559. is a sequence of size bytes. The fwrite function stops writing 
  78560. when it has written nmemb items of data or if an error condition 
  78561. is encountered on stream. The fwrite function doesn’t change 
  78562. the contents of the array pointed to by ptr.
  78563. The size parameter is typically sizeof(*ptr), where sizeof 
  78564. specifies the length of an item pointed to by ptr. 
  78565.  
  78566.                            Return values
  78567.  
  78568. The fread and fwrite functions return the number of items read 
  78569. or written. If nmemb is 0 or negative, no characters are read or 
  78570. written and 0 is returned by both fread and fwrite.
  78571.  
  78572. See also
  78573. fopen, getc, gets, printf, putc, puts, read, scanf, stdio, write
  78574.  
  78575. æKY fseek
  78576. rewind
  78577. ftell
  78578. fgetpos
  78579. fsetpos
  78580. æFc StdIO.h
  78581. æC                           Synopsis
  78582.  
  78583. #include <StdIO.h>
  78584. #define SEEK_SET 0
  78585. #define SEEK_CUR 1
  78586. #define SEEK_END 2
  78587. int fseek(FILE *stream, long int offset, int whence);
  78588. void rewind(FILE *stream);
  78589. long int ftell(FILE *stream);
  78590. int fgetpos(FILE *stream, fpos_t *pos);  
  78591. int fsetpos(FILE *stream, const fpos_t *pos);  
  78592.  
  78593.                            Description
  78594.  
  78595. The fseek; function sets the position of the next input or 
  78596. output operation on the stream. 
  78597. The value of whence determines how the offset parameter is 
  78598. used, according to these rules:
  78599.  
  78600.  If whence is SEEK_SET, the new position is offset bytes from 
  78601. the beginning of the file.
  78602.  
  78603.  If whence is SEEK_CUR, the new position is the current location 
  78604. plus offset.
  78605.  
  78606.  If whence is SEEK_END, the new position is the size of the file 
  78607. plus offset.
  78608.  
  78609.  If whence is SEEK_SET or SEEK_CUR, the value of offset may be 
  78610. negative.
  78611.  
  78612. The call rewind;(stream) is equivalent to fseek(stream, 0L, 0) 
  78613. except that the rewind call returns no value.
  78614. The fseek and rewind functions undo any effects of ungetc.
  78615. After fseek or rewind, the next operation on a file opened for 
  78616. update may be either input or output.
  78617.  
  78618. The ftell; function returns the offset of the current byte 
  78619. relative to the beginning of the file associated with the named 
  78620. stream.
  78621.  
  78622. The fgetpos; function stores the current value of the file 
  78623. position indicator for stream in the object that pos points to. 
  78624. This value contains information used by fsetpos, which 
  78625. repositions the stream to the position it held at the time the 
  78626. fgetpos function was called.  
  78627.  
  78628. The fsetpos; function is used in conjunction with the the 
  78629. fgetpos function. The fsetpos function determines the position 
  78630. for stream according to the value of pos returned by an earlier 
  78631. call to the fgetpos function on the same stream. 
  78632.  
  78633. If a call to the fsetpos function is successful, it clears the end-
  78634. of-file indicator for the stream, undoing any effects of the 
  78635. ungetc function on that stream. After an fsetpos call on the 
  78636. stream, the next operation may be either input or output.  
  78637.  
  78638.                            Return values
  78639.   
  78640. The fseek function returns nonzero for improper seeks; 
  78641. otherwise it returns zero. An example of an improper seek is 
  78642. an fseek before the beginning of, or past the end of, the file.
  78643. The getpos and fsetpos functions return zero if successful. If 
  78644. the fgetpos or fsetpos functions fail, they return nonzero and 
  78645. place a positive value in errno.  
  78646.  
  78647. See also
  78648. lseek, fopen, stdio, ungetc
  78649.  
  78650. æKY getc
  78651. getchar
  78652. fgetc
  78653. getw 
  78654. æFc StdIO.h
  78655. æC                           Synopsis
  78656.  
  78657. #include <StdIO.h>
  78658. int getc (FILE *stream);
  78659. int getchar(void);
  78660. int fgetc (FILE *stream);
  78661. int getw (FILE *stream);
  78662.  
  78663.                            Description
  78664.  
  78665. The getc; macro returns the next character from the named 
  78666. input stream. It also moves the file pointer, if defined, ahead 
  78667. one character in stream. The macro getc cannot be used if a 
  78668. function is necessary; for example, you cannot have a function 
  78669. pointer point to it. The macro getc returns the integer EOF on 
  78670. end-of-file or error.
  78671.  
  78672. The getchar; macro returns the next character from the 
  78673. standard input stream, stdin.
  78674.  
  78675. The fgetc; function produces the same result as macro getc; 
  78676. function fgetc runs more slowly than macro getc but takes less 
  78677. space per invocation. You can also have a pointer to fgetc but 
  78678. not to getc.
  78679.  
  78680. The getw; function returns the next int (that is, four bytes) 
  78681. from the named input stream so that the order of bytes in the 
  78682. stream corresponds to the order of bytes in memory. The 
  78683. function getw returns the constant EOF upon end-of-file or 
  78684. error. Because EOF is a valid integer value, feof and ferror 
  78685. should be used to check the success of getw. The function getw 
  78686. increments the associated file pointer, if defined, to point to 
  78687. the next A. The function A assumes no special alignment in the 
  78688. file.
  78689.  
  78690.                            Return values
  78691.  
  78692. These calls return data from the stream, or the integer constant 
  78693. EOF (–1) at end-of-file or upon an error.
  78694.  
  78695.                            Note
  78696.  
  78697. Because it is implemented as a macro, getc treats a stream 
  78698. parameter with side effects incorrectly. In particular,
  78699. getc(*f++)
  78700. doesn’t work as you would expect. Instead use
  78701. fgetc(*f++)
  78702.  
  78703. See also
  78704. ferror, fopen, fread, gets, putc, scanf, setbuf, stdio, ungetc
  78705.  
  78706. æKY gets
  78707. fgets
  78708. æFc StdIO.h
  78709. æC                           Synopsis
  78710.  
  78711. #include <StdIO.h>
  78712. char *gets(char *s)
  78713. char *fgets(char *s, int n, FILE *stream);
  78714.  
  78715.                            Description
  78716.  
  78717. The gets; function reads characters from the standard input 
  78718. stream, stdin, into the array pointed to by s until a newline 
  78719. character is read or an end-of-file condition is encountered. 
  78720. The newline character is discarded, and the string is 
  78721. terminated with a null (\0) character. (For more information 
  78722. about newline, see “Character Constants: Newline, 
  78723. Carriage=Return, and Vertical=Tab” in Chapter 2.)
  78724.  
  78725. The fgets; function reads characters from stream into the 
  78726. array pointed to by s until maxlen–1 characters are read, a 
  78727. newline character is read and transferred to s, or an end-of-file 
  78728. condition is encountered. The string is then terminated with a 
  78729. null character.
  78730.  
  78731.                            Return values
  78732.  
  78733. If end-of-file is encountered and no characters have been read, 
  78734. no characters are transferred to s and NULL is returned. If a 
  78735. read error occurs, NULL is returned. Otherwise s is returned. 
  78736. (A read error will occur, for example, if you attempt to use 
  78737. these functions on a file that has not been opened for reading.)
  78738.  
  78739.                            Note
  78740.  
  78741. The array pointed to by s is assumed to be large enough; 
  78742. overflow is not checked.
  78743. The function gets omits the newline character in the string; 
  78744. fgets leaves it in.
  78745.  
  78746. See also
  78747. ferror, fopen, fread, getc, scanf, stdio
  78748.  
  78749. æKY printf
  78750. fprintf
  78751. sprintf
  78752. vprintf
  78753. vfprintf
  78754. vsprintf
  78755. æFc StdIO.h
  78756. æC                           Synopsis
  78757.  
  78758. #include <StdIO.h>
  78759. int printf(const  char *format, ...);
  78760. int fprintf(FILE *stream, const  char *format, ...);
  78761. int sprintf(char *s, const  char *format, ...);
  78762. int vprintf(const  char *format, va_list arg);
  78763. int vfprintf(FILE *stream, const  char *format, va_list arg);
  78764. int vsprintf(char *s, const  char *format, va_list arg);
  78765.  
  78766.                            Description
  78767.  
  78768. The printf; function places formatted output on the standard 
  78769. output stream stdout. The fprintf; function places formatted 
  78770. output on the named output stream stream. The sprintf; 
  78771. function places formatted output, followed by the null character 
  78772. (\0), into the character array pointed to by s; it’s your 
  78773. responsibility to ensure that enough room is available. Each 
  78774. function returns the number of characters transmitted (not 
  78775. including the \0 in the case of sprintf), or a negative value if an 
  78776. output error was encountered.
  78777.  
  78778. The vprintf;, vfprintf; , and vsprintf; functions handle 
  78779. formatted output in the same manner as printf, fprintf, and 
  78780. sprintf, but the variable argument lists are replaced by va_list 
  78781. arg. The va_list is initialized by the va_start macro, as 
  78782. described later in this chapter under  “Variable Arguments—
  78783. StdArg.h.” Each of these functions invokes the va_arg macro, 
  78784. but not the va_end macro.
  78785.  
  78786. Each of these functions converts, formats, and prints its 
  78787. parameters under control of the format parameter. The format 
  78788. is a character string that contains two types of objects: plain 
  78789. characters, which are simply copied to the output stream, and 
  78790. conversion specifications, each of which results in fetching 
  78791. zero or more parameters. The behavior of the function is 
  78792. undefined if there are insufficient parameters for the format. 
  78793. If the format is exhausted while parameters remain, the extra 
  78794. parameters are ignored.
  78795.  
  78796. Each conversion specification is introduced by the character %. 
  78797. After %, the following elements appear in sequence:
  78798.  
  78799. 1.   Zero or more flag characters, which modify the meaning of 
  78800.      the conversion specification.
  78801. 2.   An optional decimal digit string specifying a minimum field 
  78802.      width. If the converted value has fewer characters than the 
  78803.      field width, it will be padded to the field width on the left 
  78804.      (default) or right (if the left-adjustment flag has been given); 
  78805.      flag specification is given after this list.
  78806. 3.   A precision that gives the minimum number of digits to 
  78807.      appear for the d, i, o, u, x, or X conversions; the number of 
  78808.      digits to appear after the decimal point for the e, E, and f 
  78809.      conversions; the maximum number of significant digits for 
  78810.      the g and G conversions; or the maximum number of 
  78811.      characters to be printed from a string in the s conversion. 
  78812.      The format of the precision is a period (.) followed by a 
  78813.      decimal digit string; a null digit string is treated as zero.  
  78814. 4.   An optional h specifies that a following d, i, o, u, x, or X 
  78815.      conversion is an unsigned or short int. An optional l 
  78816.      specifying that a following d, i, o, u, x, or X conversion 
  78817.      character applies to an arg parameter of type long int. The l 
  78818.      option is ignored in this implementation because type int 
  78819.      and type long both require 32 bits. An optional L specifies 
  78820.      that the following e, E, f, g, or G conversion is a long double.
  78821. 5.   A character that indicates the type of conversion to be applied.
  78822.  
  78823.                            Note
  78824.  
  78825. A field width or precision may be indicated by an 
  78826. asterisk (*) instead of a digit string. In this case, an integer 
  78827. arg parameter supplies the field width or precision. The arg 
  78828. parameter that is actually converted is not fetched until the 
  78829. conversion letter is seen; therefore, the arg parameters 
  78830. specifying field width or precision must appear immediately 
  78831. before the arg parameter (if any) to be converted.
  78832.  
  78833. These are the flag characters; and their meanings:
  78834.  
  78835. –    The result of the conversion will be left justified within the field.
  78836.  
  78837. +    The result of a signed conversion always begins with a sign (+ or –).
  78838.  
  78839. space    If the first character of a signed conversion is not a 
  78840.          sign, a space will be prefixed to the result. This 
  78841.          implies that if the space and + flags both appear, 
  78842.          the space flag will be ignored.
  78843.  
  78844. #    The value is to be converted to an alternate form. 
  78845.      For c, d, s, and u conversions, the flag has no 
  78846.      effect. For o conversion, it increases the precision 
  78847.      to force the first digit of the result to be a zero. For 
  78848.      x (X) conversion, a nonzero result will have 0x (0X) 
  78849.      prefixed to it. For e, E, f, g, and G conversions, the 
  78850.      result will always contain a decimal point, even if 
  78851.      no digits follow the point. (Normally, a decimal 
  78852.      point appears in the result of these conversions 
  78853.      only if a digit follows it.) For g and G conversions, 
  78854.      trailing zeros in the fractional part will not be 
  78855.      removed from the result (as they normally are).
  78856.  
  78857. 0    The 0 flag pads the field with zeros on the left 
  78858.      only; this applies to d, i, o, u, x, X, e, E, f, g, and 
  78859.      G conversions. The leading zeros (following any 
  78860.      indication of sign or base) pad the field width, and 
  78861.      no space padding is performed. If both the 0 and - 
  78862.      flags appear, the 0 flag is ignored.  If a precision is 
  78863.      specified for d, i, o, u, x, and X conversions, the 0 
  78864.      flag is ignored. For other conversion, the behavior 
  78865.      is not defined.
  78866.  
  78867.      These are the conversion characters; and their meanings:
  78868.      d, i, o, u, x, X    The integer arg parameter is converted 
  78869.      to signed decimal (d or i), unsigned octal (o), unsigned 
  78870.      decimal (u), or unsigned hexadecimal notation (x or 
  78871.       X), respectively; the letters abcdef are used for x 
  78872.       conversion and the letters ABCDEF for X conversion.
  78873.      The precision specifies the minimum number of 
  78874.      digits to appear; if the value being converted can 
  78875.      be represented in fewer digits, it will be expanded 
  78876.      with leading zeros. The default precision is 1. The 
  78877.      result of converting a zero value with a precision of 
  78878.      zero is a null string.
  78879.      This specifies a pointer to an integer into which the 
  78880.      function will store the number of characters read so far.
  78881.  
  78882. f    The float, double, comp, or extended arg parameter is 
  78883.      converted to decimal notation in the form “[–]ddd.ddd ”, 
  78884.      where the number of digits after the decimal point is 
  78885.      equal to the precision specification. If the precision is
  78886.      missing, it is assumed to be 6; if the precision is 
  78887.      explicitly 0, no decimal point appears. Infinities are printed 
  78888.      in the form “[–]INF”, and NaNs are printed in the form 
  78889.      “[–]NAN(ddd)”, where ddd is a code indicating why the 
  78890.       result is not a number.
  78891.  
  78892. e, E The float, double, comp, or extended arg parameter is 
  78893.      converted in the form “[–]d.ddd e±dd”, where there 
  78894.      is one digit before the decimal point, and where the 
  78895.      number of digits after the decimal point is equal to 
  78896.      the precision. When the precision is missing, it is 
  78897.      assumed to be 6; if the precision is 0, no decimal 
  78898.      point appears. The E format code produces a 
  78899.      number with E instead of e introducing the 
  78900.      exponent. The exponent always contains at least 
  78901.      two digits. Infinities are printed as INF, and NaNs 
  78902.      are printed in the form “[–]NAN(ddd)”, where ddd is 
  78903.      a code indicating why the result is not a number.
  78904.  
  78905. g, G The float, double, comp, or extended arg parameter 
  78906.      is printed in style f or e (or in style f or E in the 
  78907.      case of a G format code), with the precision 
  78908.      specifying the number of significant digits. The 
  78909.      style used depends on the value converted: style e 
  78910.      is used only if the exponent resulting from the 
  78911.      conversion is less than –4 or greater than the 
  78912.      precision. Trailing zeros are removed from the 
  78913.      result. A decimal point appears only if it is 
  78914.      followed by a digit.
  78915.  
  78916. c    The character arg parameter is printed.
  78917.  
  78918. s    The arg parameter is taken to be a string (character 
  78919.      pointer) and characters from the string are printed 
  78920.      until a null character (\0) is encountered or the 
  78921.      number of characters indicated by the precision 
  78922.      specification is reached. If the precision is 
  78923.      missing, it is taken to be infinite, so all characters 
  78924.      up to the first null character are printed. If the 
  78925.      string pointer arg parameter has the value zero, the 
  78926.      result is undefined; a zero arg parameter yields 
  78927.      undefined results.
  78928.  
  78929. p    The arg parameter is taken to be a pointer.
  78930.  
  78931. P    The arg parameter is taken to be a Pascal string, 
  78932.      which begins with a character specifying its length 
  78933.      and does not end with a null character (\0). (This 
  78934.      conversion character was %p in MPW 2.0 C).
  78935.  
  78936. %    Print a %; no parameter is converted.
  78937.      In no case does a nonexistent or small field width cause 
  78938.      truncation of a field. If the result of a conversion is wider than 
  78939.      the field width, the field is simply expanded to contain the 
  78940.      conversion result. Characters generated by printf and fprintf 
  78941.      are printed as if putc had been called.
  78942.  
  78943. Examples
  78944. To print a date and time in the form “Sunday, July 3, 10:02”, 
  78945. where weekday and month are pointers to null-terminated strings:
  78946. printf("%s, %s %d, %.2d:%.2d", weekday, month, day, hour, min); 
  78947.  
  78948. To print pi to five decimal places:
  78949. printf("pi = %.5f", pi());
  78950.  
  78951.                            Note
  78952.  
  78953. Calling sprintf causes other Standard I/O functions to be 
  78954. loaded, even though sprintf doesn’t perform any I/O.
  78955.  
  78956. See also
  78957. ecvt, fread, putc, puts, scanf, stdio
  78958.  
  78959. æKY putc
  78960. putchar
  78961. fputc
  78962. putw
  78963. æFc StdIO.h
  78964. æC                           Synopsis
  78965.  
  78966. #include <StdIO.h>
  78967. int putc(int c, FILE *stream);
  78968. int putchar(int c);
  78969. int fputc(int c, FILE *stream);
  78970. int putw(int w, FILE *stream);
  78971.  
  78972.                            Description
  78973.  
  78974. The  putc; macro writes the integer c to the output stream at 
  78975. the current position of the file pointer. 
  78976. The macro call putchar;(c) is equivalent to putc(c, stdout).
  78977. The fputc; function behaves like the putc macro. The 
  78978. function fputc runs more slowly than macro putc but takes less 
  78979. space per invocation.
  78980.  
  78981. The putw; function writes an int (that is, four bytes) to the 
  78982. output stream at the current position of the file pointer. This 
  78983. function neither assumes nor causes special alignment in the 
  78984. file.
  78985.  
  78986. For information about buffering of output files, see the 
  78987. “Standard I/O Buffering” section, earlier in this chapter. 
  78988.  
  78989.                            Return values
  78990.  
  78991. On success, the putc, putchar, and fputc functions return zero. 
  78992. On failure, they return the constant EOF. This occurs if the file 
  78993. stream is not open for writing or if the output file cannot be 
  78994. grown. The putw function returns zero on success and a 
  78995. nonzero value on error.
  78996.  
  78997.                            Note
  78998.  
  78999. Because it is implemented as a macro, putc treats a stream 
  79000. parameter with side effects incorrectly. In particular, putc(c,*f++)
  79001. produces unexpected results. Instead, use fputc(c,*f++).
  79002.  
  79003. See also
  79004. fclose, ferror, fopen, fread, getc, printf, puts, setbuf, stdio
  79005.  
  79006. æKY puts
  79007. fputs
  79008. æFc StdIO.h
  79009. æC                           Synopsis
  79010.  
  79011. #include <StdIO.h>
  79012. int puts(const char *s);
  79013. int fputs(const char *s, FILE *stream);
  79014.  
  79015.                            Description
  79016.  
  79017. The puts; function writes the null-terminated string pointed 
  79018. to by s, followed by a newline character, to the standard output 
  79019. stream stdout.
  79020.  
  79021. The fputs; function writes the null-terminated string pointed 
  79022. to by s to the named output stream stream.
  79023. Neither function writes the terminating null character.
  79024.  
  79025.                           Return value
  79026.  
  79027. Both routines return the number of characters written, or an 
  79028. EOF if there is a write error.
  79029.  
  79030.                            Note
  79031.  
  79032. The puts function appends a newline character, whereas fputs 
  79033. does not.
  79034.  
  79035. See also
  79036. ferror, fopen, fread, printf, putc, stdio
  79037.  
  79038. æKY remove
  79039. æFc StdIO.h
  79040. æDT int myVariable = remove((const char *)filename);  
  79041.  
  79042. æC                           Synopsis
  79043.  
  79044. #include <StdIO.h>
  79045. int remove(const char *filename);  
  79046.  
  79047.                            Description
  79048.  
  79049. The remove; function removes the named file, specified by 
  79050. filename. If you subsequently attempt to use open or reopen with 
  79051. that filename, the operation will fail.  
  79052.  
  79053.                            Return values
  79054.   
  79055. The remove function returns a nonzero value if it fails, and a zero 
  79056. value if it succeeds.
  79057.  
  79058. See also  
  79059. fopen
  79060.  
  79061. æKY scanf
  79062. fscanf
  79063. sscanf
  79064. æFc StdIO.h
  79065. æC                           Synopsis
  79066.  
  79067. #include <StdIO.h>
  79068. int scanf(const  char *format, ...);
  79069. int fscanf(FILE *stream, const  char *format, ...);
  79070. int sscanf(const  char *s, const  char *format, ...);
  79071.  
  79072.                            Description
  79073.  
  79074. The scanf; function reads characters from the standard input 
  79075. stream, stdin. The ; fscanf; function reads characters from the 
  79076. named input stream stream. The sscanf; function reads 
  79077. characters from the character string s. Each function converts 
  79078. the input according to a control string (format), then stores each 
  79079. converted value into the memory pointing to the corresponding 
  79080. variable parameter.  
  79081.  
  79082. The format parameter, the control string, contains specifications 
  79083. that control the interpretation of input sequences. The format 
  79084. consists of characters to be matched in the input stream and/or 
  79085. conversion specifications that start with the character %. The 
  79086. control string may contain White-space characters (spaces and tabs)
  79087. that cause input to be read up to the next non-white-space character,
  79088. except as described later in this section.
  79089. A character (any except %) that must match the next character 
  79090. of the input stream. (To match a % character in the input 
  79091. stream, use %%.)
  79092. Conversion specifications beginning with the character % and 
  79093. followed by an optional assignment suppression character *, 
  79094. an optional numeric maximum field width, an optional l, L, or 
  79095. h indicating the size of the receiving parameter, and a 
  79096. conversion code.
  79097. An input field is defined relative to its conversion 
  79098. specification. The input field ends when the first character 
  79099. inappropriate for conversion is encountered or when the 
  79100. specified field width is exhausted. After conversion, the input 
  79101. pointer points to the inappropriate character.
  79102. A conversion specification directs the conversion of the next 
  79103. input field; the result is placed in the variable pointed to by 
  79104. the corresponding parameter, which is a pointer to a basic C 
  79105. type such as int or float.
  79106. Assignment can be suppressed by preceding a format 
  79107. character with the character *. Assignment suppression means an 
  79108. input field is skipped: the field is read and converted but not 
  79109. assigned. Therefore, a corresponding pointer argument should 
  79110. be omitted for each suppressed input field.
  79111. The format character dictates the interpretation of the input 
  79112. field. The following format characters; are legal in a 
  79113. conversion specification, after %:
  79114.  
  79115. %    A single % is expected in the input at this point; no 
  79116.      assignment is done.
  79117.  
  79118. d    A decimal integer is expected; the corresponding 
  79119.      parameter should be an integer pointer.
  79120.  
  79121. i    A pointer to an integer is expected as the argument, 
  79122.      and the input field is interpreted as an integer. 
  79123.      The format of the number determines its base. If 
  79124.      the first characters are 0x or 0X, the number is 
  79125.      interpreted as hexadecimal. If the first character is 
  79126.      0, the number is interpreted as octal. In all other 
  79127.      cases, the number is interpreted as decimal.
  79128.      This specifies a pointer to an integer into which the 
  79129.      function will store the number of characters read 
  79130.      so far.
  79131.  
  79132. u    An unsigned decimal integer is expected; the 
  79133.      corresponding parameter should be an unsigned 
  79134.      integer pointer.
  79135.  
  79136. o    An octal integer is expected; the corresponding 
  79137.       parameter should be an integer pointer.
  79138.  
  79139. x    A hexadecimal integer is expected; the 
  79140.      corresponding parameter should be an integer 
  79141.      pointer.
  79142.      The conversion characters d, u, o, and x may be 
  79143.      preceded by l or h to indicate that a pointer to long 
  79144.      or short, rather than int, is in the parameter list. 
  79145.      The l is ignored in this implementation because int 
  79146.      and long are both 32 bits.
  79147.  
  79148. e, f, g  
  79149.      A floating-point number is expected; the next field 
  79150.      is converted accordingly and stored through the 
  79151.      corresponding parameter, which should be a 
  79152.      pointer to a float, double, comp, or extended, 
  79153.      depending on the size specification. The input 
  79154.      format for floating-point numbers is an optionally 
  79155.      signed string of digits, possibly containing a 
  79156.      decimal point, followed by an optional exponent 
  79157.      field consisting of E or e followed by an optionally 
  79158.      signed integer. In addition, infinity is represented 
  79159.      by the string "INF", and NaNs are represented by 
  79160.      the string "NAN", optionally followed by 
  79161.      parentheses that may contain a string of digits (the 
  79162.      NaN code). Case is ignored in the infinity and NaN 
  79163.      strings.
  79164.      The conversion characters e, f, and g may be 
  79165.      preceded by l, m, or L to indicate that a pointer to 
  79166.      double, comp, or extended, rather than float, is in the 
  79167.      parameter list.
  79168.  
  79169. s    A character string is expected; the corresponding 
  79170.      parameter should be a character pointer to an array 
  79171.      of characters large enough to accept the string; a 
  79172.      terminating null character (\0) is added 
  79173.      automatically. The input field is terminated by a 
  79174.      white-space (blank or tab) character, or when the 
  79175.      number of characters specified by the maximum 
  79176.      field width has been read.
  79177.  
  79178. p    A pointer is expected as the argument.
  79179.  
  79180. P    A character string is expected. The next field is 
  79181.      converted to a Pascal string, that is, a length byte 
  79182.      followed by the string itself, without a terminating 
  79183.      null character (\0). The corresponding parameter 
  79184.      should be a pointer to an array of characters large 
  79185.      enough to accept the string. The input field is 
  79186.      terminated by a white space (blank or tab) 
  79187.      character, or when the number of characters 
  79188.      specified by the maximum field width has been 
  79189.      read. (This was %p in MPW 2.0 C).
  79190.  
  79191. c    A character is expected; the corresponding 
  79192.      parameter should be a character pointer. The 
  79193.      normal skip over white space is suppressed in this 
  79194.      case; use %1s (digit one) to read the next non-white-
  79195.      space character. If a field width is given, the 
  79196.      corresponding parameter should refer to a 
  79197.      character array; the indicated number of characters 
  79198.      is read.
  79199.  
  79200. [    The left bracket introduces a scanset format. The 
  79201.      input field is the maximal sequence of input 
  79202.      characters consisting entirely of characters in the 
  79203.      scanset. When reading the input field, the normal 
  79204.      skip over leading white space is suppressed. The 
  79205.      corresponding pointer parameter must point to a 
  79206.      character array large enough to hold the input field 
  79207.      and the terminating null character (\0), which will 
  79208.      be added automatically. The left bracket is followed 
  79209.      by a set of characters (the scanset) and a 
  79210.      terminating right bracket.
  79211.  
  79212. ^    When it appears as the first character in the 
  79213.      scanset, the circumflex (^) serves as a complement 
  79214.      operator and redefines the scanset as the set of all 
  79215.      characters not contained in the remainder of the 
  79216.      scanset string.
  79217.  
  79218. ]    The right bracket ends the scanset. To be included 
  79219.      as an element of the scanset, the right bracket must 
  79220.      appear as the first character (possibly preceded 
  79221.      by a circumflex) of the scanset. Otherwise, it will 
  79222.      be interpreted syntactically as the closing bracket.
  79223.      A range of characters may be represented by the 
  79224.      construct first-last; thus the scanset [0123456789] 
  79225.      may be expressed [0-9]. To use this convention, 
  79226.      first must be less than or equal to last in the ASCII 
  79227.      collating sequence. Otherwise, the minus (–) will 
  79228.      stand for itself in the scanset. The minus will also 
  79229.      stand for itself whenever it is the first or the last 
  79230.      character in the scanset.
  79231.  
  79232.      At least one character must match for the 
  79233.      conversion to be considered successful.
  79234.      Conversion terminates at EOF, at the end of the control string, 
  79235.      or when an input character doesn’t match the control string. In 
  79236.      the last case, the unmatched character is left unread in the 
  79237.      input stream.
  79238.  
  79239. Examples
  79240. The following examples show how scanf works.
  79241.  
  79242. Example 1: 
  79243. The call
  79244. int i;
  79245. float x;
  79246. char name[50];
  79247. scanf("%d%f%s", &i, &x, name);
  79248. with input
  79249. 25 54.32E-1 Louisa
  79250. will assign the value 25 to i and value 5.432 to x, and put 
  79251. Louisa\0 into name.
  79252.  
  79253. Example 2: 
  79254. The call
  79255. int i;
  79256. extended x;
  79257. char name[50];
  79258. scanf("%2d%nf%*d %[0-9]", &i, &x, name);
  79259. with input
  79260. 56789 0123 56a72
  79261. will assign the value 56 to i and the value 789.0 to x, skip 0123, 
  79262. and put 56\0 into name. The next call to getchar will return a.
  79263.  
  79264. Example 3: 
  79265. The call
  79266. int i;
  79267. scanf("answer1=%d", &i);
  79268. with input
  79269. answer1=51 answer2=45
  79270. will assign the value 51 to i because "answer1" is matched 
  79271. explicitly in the input stream; the input pointer will be left at 
  79272. the space before "answer2".
  79273.  
  79274.                           Return value
  79275.  
  79276. The scanf, fscanf, and sscanf functions return the number of 
  79277. successfully matched and assigned input items; this number 
  79278. can be 0 when an early mismatch between an input character 
  79279. and the control string occurs. If the input ends before the first 
  79280. mismatch or conversion, EOF is returned.
  79281. These functions return EOF on end of input and a short count 
  79282. for missing or illegal data items.
  79283.  
  79284.                            Note
  79285.  
  79286. Trailing white space is left unread unless matched in the 
  79287. control string.
  79288. The success of literal matches and suppressed assignments is 
  79289. not directly determinable.
  79290.  
  79291.                            Warning
  79292.  
  79293. The pointer variable parameters to scanf, fscanf, and sscanf must be 
  79294. pointers—for example, &i. Be sure to pass the address of i rather than 
  79295. its value.
  79296.  
  79297. See also
  79298. atof, atoi, fread, getc, gets, printf, stdio, strtol
  79299. Apple Numerics Manual, 2nd edition
  79300.  
  79301. æKY setbuf
  79302. setvbuf
  79303. æFc StdIO.h
  79304. æC                           Synopsis
  79305.  
  79306. #include <StdIO.h>
  79307. void setbuf (FILE *stream, char *buf); 
  79308. int setvbuf(FILE *stream, char *buf, int mode, size_t size);
  79309.  
  79310.                            Description
  79311.  
  79312. A buffer is normally allocated by the Standard C Library at the 
  79313. time of the first getc or putc on a file. If you prefer to provide 
  79314. your own buffer, you can call setbuf or setvbuf after a stream 
  79315. has been associated with an open file but before it is read or 
  79316. written. The functions setbuf and setvbuf let you provide your 
  79317. own buffering for a file stream. The function setvbuf is a more 
  79318. flexible extension of setbuf.
  79319.  
  79320. The setbuf; function causes the character array pointed to by 
  79321. buf to be used instead of an automatically allocated buffer. 
  79322. BUFSIZ, a constant defined in the <StdIO.h> header file, lets 
  79323. you specify the size of the buf array as
  79324. char buf[BUFSIZ];
  79325.  
  79326. If buf is NULL, input/output is unbuffered.
  79327. The setvbuf; function lets you specify two parameters in 
  79328. addition to those required by setbuf: size and mode. Parameter 
  79329. size specifies the size in bytes of the array to be used; the 
  79330. standard I/O functions work most efficiently when size is a 
  79331. multiple of BUFSIZ. If buffer pointer buf is NULL, a buffer of size 
  79332. bytes is allocated from the system. If size is not 0, size is 
  79333. assigned to the FILE variable’s size parameter; if buf is not NULL, 
  79334. buf is assigned to the FILE variable’s buffer-pointer parameter. 
  79335. The value of mode determines how stream is buffered by 
  79336. setvbuf:
  79337.  
  79338.  
  79339. Value of mode    Description
  79340.  
  79341. _IOFBF           Causes input/output to be file buffered.
  79342. _IOLBF           Causes output to be line buffered. The buffer is 
  79343.                  flushed when a newline character is written or 
  79344.                  when the buffer is full.
  79345. _IONBF           Causes input/output to be unbuffered. Parameters 
  79346.                  buf and size are ignored.
  79347.  
  79348. The following function calls are equivalent when buf is not 
  79349. NULL:
  79350. setbuf(stream, buf);
  79351. setvbuf(stream, buf, _IOFBF, BUFSIZ);
  79352.  
  79353. The following function calls are equivalent when buf is NULL:
  79354. setbuf(stream, NULL);
  79355. setvbuf(stream, NULL, _IONBF, 0);
  79356.  
  79357.                           Diagnostics
  79358.  
  79359. The function setvbuf returns nonzero if an invalid value is 
  79360. given for mode.
  79361.  
  79362.                            Note
  79363.  
  79364. The buffer must have a lifetime at least as great as the open 
  79365. stream. Be sure to close the stream before the buffer is 
  79366. deallocated. If you allocate buffer space as an automatic 
  79367. variable in a code block, be sure to close the stream in the 
  79368. same block.
  79369. If buf is NULL and the system cannot allocate size bytes, a 
  79370. smaller buffer will be allocated.
  79371.  
  79372. See also
  79373. fclose, fopen, getc, malloc, putc, stdio, ungetc
  79374.  
  79375. æKY tmpfile
  79376. æFc StdIO.h
  79377. æDT FILE * myVariable = tmpfile();   
  79378.  
  79379. æC                           Synopsis
  79380.  
  79381. #include <StdIO.h>
  79382. FILE *tmpfile(void);  
  79383.  
  79384.                            Description
  79385.  
  79386. The tmpfile; function creates and opens a temporary binary 
  79387. file. This file is automatically removed when it is closed or 
  79388. when the program terminates. 
  79389.  
  79390.                            Return values
  79391.   
  79392. The tmpfile function returns a null pointer if the temporary file 
  79393. cannot be created. If the tmpfile operation succeeds, it returns 
  79394. a pointer to the stream of the temporary file.
  79395.  
  79396. See also  
  79397. fopen
  79398.  
  79399. æKY tmpnam
  79400. æFc StdIO.h
  79401. æDT  char * myVariable = tmpnam((char *)s);
  79402.  
  79403. æC                           Synopsis
  79404.  
  79405. #include <StdIO.h>
  79406. char *tmpnam(char *s);  
  79407.  
  79408.                            Description
  79409.  
  79410. The tmpnam; function creates a string that can be used as a 
  79411. valid filename. This string is not the same as the name of any 
  79412. existing file. The tmpnam function generates a different filename 
  79413. each time it is called, and can be called up to TMP_MAX times 
  79414. during program execution. 
  79415.  
  79416.                            Return values
  79417.   
  79418. With an argument of tmpnam(NULL), the tmpnam function places its 
  79419. result in an internal static object and returns a pointer to that 
  79420. string. Subsequent calls may modify this string. With an 
  79421. argument of tmpnam(s), the variable s points to an array of at 
  79422. least L_tmpnam chars; the tmpnam function then places its result 
  79423. in that array before returning the argument as its value.  
  79424.  
  79425. See also  
  79426. fopen
  79427.  
  79428. æKY ungetc
  79429. æFc StdIO.h
  79430. æDT int myVariable = ungetc ((int) c, (FILE *)stream);
  79431.  
  79432. æC                           Synopsis
  79433.  
  79434. #include <StdIO.h>
  79435. int ungetc (int c, FILE *stream);
  79436.  
  79437.                            Description
  79438.  
  79439. The ungetc; function inserts the integer c into the buffer 
  79440. associated with an input stream. The stream must be file 
  79441. buffered or line buffered; it cannot be unbuffered. The 
  79442. inserted character, c, will be returned by the next getc call on 
  79443. that stream. The ungetc function returns c and leaves the file 
  79444. stream unchanged.
  79445.  
  79446. Only one character of pushback is allowed, provided 
  79447. something has been read from the stream and the stream is not 
  79448. unbuffered.
  79449.  
  79450. If c equals EOF, ungetc does nothing to the buffer and returns 
  79451. EOF. In other words, you cannot use ungetc to force yourself to 
  79452. the end-of-file the next time you read the file.
  79453. The fseek function undoes the effect of ungetc.
  79454.  
  79455.                           Diagnostics
  79456.  
  79457. For ungetc to perform correctly, a read must have been 
  79458. performed before the call to the ungetc function. The function 
  79459. ungetc returns EOF if it can’t insert the character.
  79460.  
  79461.                            Note
  79462.  
  79463. The function ungetc does not work on unbuffered streams.
  79464.  
  79465. See also
  79466. fseek, getc, setbuf, stdio
  79467.  
  79468.  
  79469.  
  79470. æKY fcloseæ 
  79471. æDT 
  79472. int myVariable = fclose((FILE *)stream);
  79473.  
  79474. æKY fflushæ 
  79475. æDT 
  79476. int myVariable = fflush((FILE *)stream);
  79477.  
  79478. æKY feofæ 
  79479. æDT 
  79480. int myVariable = feof((FILE *)stream);
  79481.  
  79482. æKY ferroræ 
  79483. æDT 
  79484. int myVariable = ferror((FILE *)stream);
  79485.  
  79486. æKY clearerræ 
  79487. æDT 
  79488. clearerr((FILE *)stream);
  79489.  
  79490. æKY perroræ 
  79491. æDT 
  79492. perror((const char *)s);
  79493.  
  79494. æKY filenoæ 
  79495. æDT 
  79496. int myVariable = fileno((FILE *)stream);
  79497.  
  79498.  
  79499. æKY fopenæ 
  79500. æDT 
  79501. FILE * myVariable = fopen((const char *)filename, (const char *)mode);
  79502.  
  79503. æKY freopenæ 
  79504. æDT 
  79505. FILE * myVariable = freopen((const char *)filename, (const char *)mode, (FILE *)stream);
  79506.  
  79507. æKY fdopenæ
  79508. æDT 
  79509. FILE * myVariable = fdopen((int) fildes, (char *)type);
  79510.  
  79511.  
  79512. æKY freadæ 
  79513. æDT 
  79514. size_t myVariable =  fread((void *)ptr, (size_t) size, (size_t) nmemb, (FILE *)stream);
  79515.  
  79516. æKY fwriteæ 
  79517. æDT 
  79518. int myVariable = fwrite((const  void *)ptr, (size_t) size, (size_t) nmemb, (FILE *)stream);
  79519.  
  79520.  
  79521. æKY fseekæ 
  79522. æDT 
  79523. int myVariable = fseek((FILE *)stream, (long int) offset, (int) whence);
  79524.  
  79525. æKY rewindæ 
  79526. æDT 
  79527. rewind((FILE *)stream);
  79528.  
  79529. æKY ftellæ 
  79530. æDT 
  79531. long int myVariable = ftell((FILE *)stream);
  79532.  
  79533. æKY fgetposæ
  79534. æDT 
  79535. int myVariable = fgetpos((FILE *)stream, (fpos_t *)pos); 
  79536.  
  79537. æKY fsetposæ
  79538. æDT 
  79539. int myVariable = fsetpos((FILE *)stream, (const fpos_t *)pos);  
  79540.  
  79541.  
  79542. æKY getcæ 
  79543. æDT 
  79544. int myVariable = getc ((FILE *)stream);
  79545.  
  79546. æKY getcharæ 
  79547. æDT 
  79548. int myVariable = getchar();
  79549.  
  79550. æKY fgetcæ 
  79551. æDT 
  79552. int myVariable = fgetc ((FILE *)stream);
  79553.  
  79554. æKY getwæ 
  79555. æDT 
  79556. int myVariable = getw ((FILE *)stream);
  79557.  
  79558.  
  79559. æKY getsæ 
  79560. æDT 
  79561. char * myVariable = gets((char *)s);
  79562.  
  79563. æKY fgetsæ 
  79564. æDT 
  79565. char * myVariable = gets((char *)s, (int) n, (FILE *)stream);
  79566.  
  79567.  
  79568. æKY printfæ 
  79569. æDT 
  79570. int myVariable = printf((const  char *)format, ...);
  79571.  
  79572. æKY fprintfæ
  79573. æDT 
  79574. int myVariable = fprintf((FILE *)stream, (const  char *)format, ...);
  79575.  
  79576. æKY sprintfæ 
  79577. æDT 
  79578. int myVariable = sprintf((char *)s, (const  char *)format, ...);
  79579.  
  79580. æKY vprintfæ 
  79581. æDT 
  79582. int myVariable = vprintf((const  char *)format, (va_list) arg);
  79583.  
  79584. æKY vfprintfæ 
  79585. æDT 
  79586. int myVariable = vfprintf((FILE *)stream, (const  char *)format, (va_list) arg);
  79587.  
  79588. æKY vsprintfæ 
  79589. æDT 
  79590. int myVariable = vsprintf((char *)s, (const  char *)format, (va_list) arg);
  79591.  
  79592. æKY putcæ 
  79593. æDT 
  79594. int myVariable = putc((int) c, (FILE *)stream);
  79595.  
  79596.  
  79597. æKY putcharæ 
  79598. æDT 
  79599. int myVariable = putchar((int) c);
  79600.  
  79601. æKY fputcæ 
  79602. æDT 
  79603. int myVariable = fputc((int) c, (FILE *)stream);
  79604.  
  79605. æKY putwæ 
  79606. æDT 
  79607. int myVariable = putw((int) w, (FILE *)stream);
  79608.  
  79609.  
  79610. æKY putsæ 
  79611. æDT 
  79612. int myVariable = puts((const char *)s);
  79613.  
  79614. æKY fputsæ 
  79615. æDT 
  79616. int myVariable = fputs((const char *)s, (FILE *)stream);
  79617.  
  79618.  
  79619.  
  79620. æKY scanfæ 
  79621. æDT 
  79622. int myVariable = scanf((const  char *)format, ...);
  79623.  
  79624. æKY fscanfæ 
  79625. æDT 
  79626. int myVariable = fscanf((FILE *)stream, (const  char *)format, ...);
  79627.  
  79628. æKY sscanfæ 
  79629. æDT 
  79630. int myVariable = sscanf((const  char *)s, (const  char *)format, ...);
  79631.  
  79632. æKY setbufæ 
  79633. æDT 
  79634. setbuf ((FILE *)stream, (char *)buf); 
  79635.  
  79636. æKY setvbufæ 
  79637. æDT 
  79638. int myVariable = setvbuf((FILE *)stream, (char *)buf, (int) mode, (size_t) size);
  79639.  
  79640.  
  79641.  
  79642.  
  79643. æKY StdLib.h
  79644. æFc StdLib.h
  79645. æC 
  79646. abort      calloc    malloc      srand
  79647. abs        div       mblen       strtod
  79648. atexit     exit      mbstowcs    strtol
  79649. atof       free      mbtowc      strtoul
  79650. atoi       getenv    qsort       wcstombs
  79651. atol       labs      rand        wctomb
  79652. bsearch    ldiv      realloc     
  79653.  
  79654. Synopsis
  79655.  
  79656. #include <StdLib.h>
  79657. #define  NULL 0
  79658.  
  79659. typedef struct {     /* structure type returned by div function */
  79660.  int quot;
  79661.  int rem;
  79662.  }  div_t;
  79663. typedef struct {     /* structure type returned by ldiv function */
  79664.  long int quot;
  79665.  long int rem;
  79666.  }  ldiv_t;
  79667.  
  79668. #define EXIT_FAILURE 1       /* arguments to the exit function */
  79669. #define EXIT_SUCCESS 0
  79670. #define RAND_MAX     32767   /* maximum that rand function can return */
  79671. #define MB_CUR_MAX   1       /* maximum number of bytes in a
  79672.                                  multibyte character */
  79673.  
  79674. æKY abort
  79675. æFc StdLib.h
  79676. æC                           Synopsis
  79677.  
  79678. #include <StdLib.h>
  79679. void abort (void);
  79680.  
  79681.                            Description
  79682.  
  79683. The abort; function requests a program to terminate with 
  79684. error status. It is equivalent to the following program fragment:
  79685. raise (SIGABRT);
  79686. exit (ABORT_STATUS); /* ABORT_STATUS is used for illustration */
  79687.                          /* only. Any non-zero value will do */
  79688.  
  79689. The request will be honored unless you install a signal handler for 
  79690. the signal SIGABRT, and your signal handler doesn’t return 
  79691. (that is, it exits by calling longjmp).
  79692.  
  79693. See also
  79694. signal, raise, longjmp, assert, exit, atexit
  79695.  
  79696. æKY abs
  79697. labs
  79698. æFc StdLib.h
  79699. æC                           Synopsis
  79700.  
  79701. #include <StdLib.h>
  79702. int abs (int i);
  79703. long int labs (long int j);
  79704.  
  79705. The abs; function returns the absolute value of i.
  79706. The labs; function returns the absolute value of long integer j.
  79707.  
  79708.                            Note
  79709.  
  79710. The absolute value of the negative integer with the largest 
  79711. magnitude is undefined.
  79712.  
  79713. See also
  79714. floor
  79715.  
  79716. æKY atexit
  79717. æFc StdLib.h
  79718. æC                           Synopsis
  79719.  
  79720. #include <StdLib.h>
  79721. int atexit(void (*func)(void));
  79722.  
  79723.                            Description
  79724.  
  79725. The atexit; function installs the exit function pointed to by 
  79726. func, by adding it to a list. The list is initially empty. A list 
  79727. entry is added whenever atexit is called. The function exit 
  79728. calls the functions in the list in the reverse order to that in 
  79729. which they were added. Programs that use the buffered I/O 
  79730. portion of the Standard I/O Package (including the predefined 
  79731. streams stdin, stdout, and stderr) need to flush all open 
  79732. buffers before the program terminates. To ensure that the 
  79733. buffers are flushed, the Standard I/O Package adds its cleanup 
  79734. function to the list the first time it allocates a buffer.
  79735.  
  79736. Each function in the list is called with an int parameter either 
  79737. at program termination or when exit is called. The argument is 
  79738. the program’s status value (zero for normal execution, nonzero 
  79739. for errors). The function can use this value or ignore it.
  79740. The number of user-supplied exit functions is limited to 32.
  79741.  
  79742.                           Diagnostics
  79743.  
  79744. The function returns a zero value if the installation succeeds.
  79745.  
  79746.                            Note
  79747.  
  79748. This function was called onexit in previous versions of MPW C.
  79749.  
  79750.                            Warning
  79751.  
  79752. If a function is installed more than once, it is executed as many 
  79753. times as it was installed.
  79754.  
  79755. See also
  79756. exit, stdio
  79757.  
  79758. æKY atof
  79759. æFc StdLib.h
  79760. æC                           Synopsis
  79761.  
  79762. #include <StdLib.h>
  79763. extended atof(const char *nptr);
  79764.  
  79765.                            Description
  79766.  
  79767. The atof; function converts a character string pointed to by 
  79768. nptr to an extended-precision floating-point number. The first 
  79769. unrecognized character ends the conversion. The function atof 
  79770. recognizes an optional string of white-space characters (spaces 
  79771. or tabs), then an optional sign, then a string of digits optionally 
  79772. containing a decimal point, then an optional e or E followed by 
  79773. an optionally signed integer. If the string begins with an 
  79774. unrecognized character, atof returns a NaN.
  79775.  
  79776. The atof function recognizes "INF" as infinity and "NAN" 
  79777. (optionally followed by parentheses that may contain a string 
  79778. of digits) as a NaN, with the NaN code given by the string of 
  79779. digits. Case is ignored in the infinity and NaN strings.
  79780.  
  79781.                           Diagnostics
  79782.  
  79783. The atof function honors the floating-point exception flags—
  79784. invalid operation, underflow, overflow, divide by zero, and 
  79785. inexact—as prescribed by SANE.
  79786.  
  79787. See also
  79788. atoi, scanf, strtol
  79789.  
  79790. æKY atoi
  79791. atol
  79792. æFc StdLib.h
  79793. æC                           Synopsis
  79794.  
  79795. #include <StdLib.h>
  79796. int atoi(const char *nptr);
  79797. long int atol(const char *nptr);
  79798.  
  79799.                            Description
  79800.  
  79801. The atoi and atol functions convert strings to integers. The 
  79802. character string nptr is scanned up to the first nondigit 
  79803. character other than an optional leading minus sign (–). Leading 
  79804. white-space characters (spaces and tabs) are ignored. 
  79805.  
  79806.                            Return values
  79807.  
  79808. The atoi; function returns as an integer the decimal value 
  79809. represented by nptr. The atol; function returns as a long 
  79810. integer the decimal value represented by nptr. On the 
  79811. Macintosh, these functions are equivalent because int and long 
  79812. are the same size.
  79813.  
  79814.                            Note
  79815.  
  79816. Overflow conditions are ignored. A plus sign (+) is considered 
  79817. a nondigit character.
  79818.  
  79819. See also
  79820. atof, scanf, strtol
  79821.  
  79822. æKY bsearch
  79823. æFc StdLib.h
  79824. æC                           Synopsis
  79825.  
  79826. #include <StdLib.h>
  79827. void *bsearch(const void *key, const void *base, size_t nmemb, size_t 
  79828.          size,int (*compar)(const void *, const void *));
  79829.  
  79830.                            Description
  79831.  
  79832. The bsearch; function searches through an array previously 
  79833. sorted into increasing order. The argument base corresponds to 
  79834. the initial array member, the size argument corresponds to the 
  79835. size of each array member, and the nmemb argument provides 
  79836. the number of members in the array. 
  79837.  
  79838. The compar; function is called from bsearch with two 
  79839. arguments; the first points to the key object, and the second 
  79840. points to an array member. The compar function compares array 
  79841. members to key until it finds one that is equal to key. When a 
  79842. match is found, compar returns a zero, and the bsearch function 
  79843. returns a pointer to the matching member of the array. If no 
  79844. matching array member is found, compar returns a nonzero 
  79845. value, and bsearch returns a null pointer.
  79846.  
  79847. See also
  79848. qsort
  79849.  
  79850. æKY div
  79851. ldiv
  79852. æFc StdLib.h
  79853. æC                           Synopsis
  79854.  
  79855. #include <StdLib.h>
  79856. div_t div (int numer, int denom);
  79857. ldiv_t ldiv (long int numer, long int denom);
  79858.  
  79859.                            Description
  79860.  
  79861. The div function divides numer by denom, computing the quotient 
  79862. and the remainder. The results are stored in the structure div_t. 
  79863.  
  79864. The ldiv function divides a long integer value numer by the long 
  79865. integer denom, computing the quotient and the remainder. The 
  79866. results are stored in the structure ldiv_t. 
  79867.  
  79868. See also
  79869. math.h
  79870.  
  79871. æKY exit
  79872. æFc StdLib.h
  79873. æC                           Synopsis
  79874.  
  79875. #include <StdLib.h>
  79876. void exit(int status);
  79877.  
  79878.                            Description
  79879.  
  79880. The exit; function closes open file descriptors and 
  79881. terminates the application or tool. Here is the order in which 
  79882. exit performs its duties:
  79883. 1.   It executes all exit procedures in reverse order of their 
  79884.      installation by atexit, including the exit procedures for the 
  79885.      Standard I/O Package if Standard I/O routines were used. All 
  79886.      buffered files are flushed and closed.
  79887. 2.   It closes all open files that were opened with open.
  79888. 3.   If the program is a tool running under the MPW shell, exit 
  79889.      places the lower three bytes of status into the shell’s status 
  79890.      variable and returns control to the MPW Shell.
  79891.      If the program is an application, exit terminates the application.
  79892.  
  79893.                            Return values
  79894.  
  79895. The main program is a function that returns an integer. The 
  79896. return value of main is interpreted by the MPW shell as the 
  79897. program status. When you call exit, the status parameter is 
  79898. returned to the MPW shell as the return value for the 
  79899. application’s main function: 0 for normal execution or a small 
  79900. positive value for errors (typically 1 to 3). A main program that 
  79901. returns to the shell without setting status to an integer value 
  79902. will appear to be returning a random status.
  79903. There is no return from exit.
  79904.  
  79905.                            Note
  79906.  
  79907. The exit function doesn’t close files you opened with calls to 
  79908. the I/O routines documented in Inside Macintosh.
  79909. Don’t call exit from a desk accessory.
  79910.  
  79911. See also
  79912. fclose, atexit, stdio
  79913.  
  79914. æKY getenv
  79915. æFc StdLib.h
  79916. æC                           Synopsis
  79917.  
  79918. #include <StdLib.h>
  79919. char *getenv(const char *name);
  79920.  
  79921.                            Description
  79922.  
  79923. The environment; is the set of exported variables provided 
  79924. by the MPW Shell. The function getenv provides access to 
  79925. variables in this set. (See “Variables” in Chapter 5 of the MPW 
  79926. 3.0 Reference for the list of standard exported shell variables.)
  79927.  
  79928. The getenv; function searches the environment for a Shell 
  79929. variable with the name specified by name and returns a pointer 
  79930. to the character string containing its value. The null pointer is 
  79931. returned if the shell variable is not defined or has not been 
  79932. exported. The shell-variable name search is case insensitive.
  79933.  
  79934.                            Return values
  79935.  
  79936. Upon successful completion, a pointer to the value of name is 
  79937. returned. If the Shell variable is not defined or not exported, 
  79938. the function returns the null pointer.
  79939. For stand-alone applications, which do not run under the MPW 
  79940. Shell, getenv always returns the null pointer.
  79941.  
  79942.                            Note
  79943.  
  79944. The environment can also be accessed by means of a parameter 
  79945. to the C main-entry-point function main; if the main procedure 
  79946. is declared as
  79947. main(argc, argv, envp)
  79948. The envp; array represents the set of MPW Shell variables 
  79949. that have been made available to tools by means of the MPW 
  79950. Export command. The ith envp entry has the form
  79951. envp[i] = "varname\0varvalue\0";
  79952. The last envp entry is the null pointer.
  79953. If you use envp to search the environment, be sure to use case-
  79954. insensitive string comparisons.
  79955.  
  79956.                            Warning
  79957.  
  79958. The getenv function returns a pointer to the place in memory 
  79959. where a copy of the MPW Shell variable resides. Do not modify 
  79960. the value of a Shell variable in such a way as to increase its 
  79961. length.  
  79962.  
  79963. æKY malloc
  79964. free
  79965. realloc
  79966. calloc
  79967. æFc StdLib.h
  79968. æC                           Synopsis
  79969.  
  79970. #include <StdLib.h>
  79971. void *malloc (size_t size);
  79972. void free (void *ptr);
  79973. void *realloc(void *ptr, size_t size);
  79974. void *calloc(size_t nmemb, size_t size);
  79975.  
  79976.                            Description
  79977.  
  79978. The malloc; and free functions provide a simple general-
  79979. purpose memory allocation package. The storage area expands 
  79980. as necessary when malloc is called.
  79981.  
  79982. The malloc function allocates the first sufficiently large 
  79983. contiguous free space it finds and returns a pointer to a block 
  79984. of at least size bytes suitably aligned for any use. It calls 
  79985. NewPtr (see Inside Macintosh) to get more memory from the 
  79986. system when there is no suitable space already free.
  79987.  
  79988. The free function takes a parameter that is a pointer to a block 
  79989. previously allocated by malloc. If its size is greater than 2K 
  79990. bytes, it is returned to the system using DisposePtr. Blocks 
  79991. smaller than that are cached by malloc for further allocation by 
  79992. malloc only. Undefined results occur if the space assigned by 
  79993. malloc is overrun or if a random value is passed to free.
  79994.  
  79995. The realloc; function changes the size of the block pointed 
  79996. to by ptr to size bytes and returns a pointer to the (possibly 
  79997. moved) block. The contents are unchanged up to the lesser of 
  79998. the new and old sizes. If no free block of size bytes is 
  79999. available in the storage area, realloc asks malloc to enlarge the 
  80000. storage area by size bytes and then moves the data to the new 
  80001. space. If ptr is NULL, realloc is equivalent to malloc.
  80002.  
  80003. The calloc function allocates space for an array of nmemb 
  80004. elements of size size. The space is initialized to zeros.
  80005.  
  80006.                            Note
  80007.  
  80008. You should not call DisposePtr directly to release memory areas 
  80009. allocated with these routines.
  80010.  
  80011.                           Diagnostics
  80012.  
  80013. The malloc, realloc, and calloc functions return a null pointer 
  80014. if there is no available memory or if the storage area has been 
  80015. detectably corrupted by storing outside the bounds of a block. 
  80016. When this happens, the block pointed to by ptr may have been 
  80017. destroyed.
  80018.  
  80019. See also
  80020. setbuf
  80021.  
  80022. æKY mblen
  80023. mbtowc
  80024. wctomb
  80025. æFc StdLib.h
  80026. æC                           Synopsis
  80027.  
  80028. #include <StdLib.h>
  80029. int mblen (const char *s, size_t n);
  80030. int mbtowc (wchar_t *pwc, const char *s, size_t n);
  80031. int wctomb (char *s, wchar_t wchar);
  80032.  
  80033.                            Description
  80034.  
  80035. The mblen; function computes the size in bytes of the 
  80036. multibyte character pointed to by s. This function is similar to
  80037. mbtowc((wchar_t *)0, s, n);
  80038. except that the mbtowc function doesn’t affect the shift state.
  80039.  
  80040. The mbtowc; function also computes the size in bytes of the 
  80041. multibyte character pointed to by s. It then determines the 
  80042. corresponding code for that multibyte character. This code has 
  80043. a value of type wchar_t. (The null character’s code has a value 
  80044. of zero.) For valid multibyte characters when pwc is not a null 
  80045. pointer, mbtowc stores the code in pwc. A maximum of n bytes of 
  80046. array s will be used. The value returned will never be greater 
  80047. than  the MB_CUR_MAX macro.  
  80048.  
  80049. The wctomb; function computes the number of bytes needed 
  80050. to represent the multibyte character corresponding to the code 
  80051. whose value is wchar (including any change in shift state). The 
  80052. wctomb function stores the multibyte character representation in 
  80053. array object  s (if s is not a null pointer). A maximum of 
  80054. MB_CUR_MAX characters are stored. If wchar is zero, wctomb 
  80055. remains in the initial shift state. The value returned will never 
  80056. be greater than the MB_CUR_MAX macro.  
  80057.  
  80058. See the section on “Locale” for information on how the 
  80059. multibyte character functions are affected by the LC_CTYPE 
  80060. category of the current locale.  
  80061.  
  80062.                            Return values
  80063.  
  80064. For the multibyte character functions, the following values may 
  80065. be returned.
  80066. If s is not a null pointer:
  80067.   0  Returned value is a null character.
  80068. –1   Returned value does not correspond to a valid 
  80069.      multibyte character.
  80070.      Otherwise, the function returns the multibyte character’s size 
  80071.      in bytes.
  80072. If s is a null pointer:
  80073. 0    Multibyte character encodings don’t have state-
  80074.      dependent encodings.
  80075. nonzero  Multibyte character encodings have state-dependent encodings.
  80076.  
  80077. See also
  80078. locale, multibyte string functions
  80079. Inside Macintosh, Volume V
  80080.  
  80081. æKY mbstowcs
  80082. wcstombs
  80083. æFc StdLib.h
  80084. æC                           Synopsis
  80085.  
  80086. #include <StdLib.h>
  80087. size_t mbstowcs (wchar_t *pwcs, const char *s, size_t n);
  80088. size_t wcstombs (char *s, const wchar_t *pwcs, size_t n);
  80089.  
  80090.                            Description
  80091.  
  80092. See the section on “Localization,” earlier in this chapter, for 
  80093. information on how the multibyte string functions are affected 
  80094. by the LC_CTYPE category of the current locale.  
  80095.  
  80096. The mbstowcs; function takes as an argument a sequence of 
  80097. multibyte characters from array s. These characters begin in 
  80098. the initial shift state and are converted into a sequence of 
  80099. corresponding codes.  Up to n codes are stored into the array 
  80100. pointed to by pwcs. Multibyte characters that follow a null 
  80101. character aren’t examined or converted. The null character 
  80102. itself is converted into a code with value zero. 
  80103. The character conversion is similar to the mbtowc function, 
  80104. except that the mbtowc function doesn’t affect the shift state. 
  80105. Copying between overlapping objects produces undefined 
  80106. results. If the mbstowcs function encounters an invalid 
  80107. multibyte character, it returns (size_t)-1. Otherwise, mbstowcs 
  80108. returns the number of array elements that were modified; it 
  80109. doesn’t include any terminating zero code.   
  80110.  
  80111. The wcstombs; function takes as an argument a sequence of 
  80112. codes from array pwcs. The wcstombs function converts these 
  80113. codes into characters beginning in the initial shift state, then 
  80114. stores these characters in array s. Conversion stops if a 
  80115. multibyte character exceeds the limit of n total bytes or if a null 
  80116. character is stored. 
  80117.  
  80118. The code conversion is similar to the wctomb function, except 
  80119. that the wctomb function doesn’t affect the shift state.  
  80120. Copying between overlapping objects produces undefined 
  80121. results. If the wcstombs function encounters a code 
  80122. corresponding to an invalid multibyte character, it returns 
  80123. (size_t)-1. Otherwise, wcstombs returns the number of bytes 
  80124. that were modified; it doesn’t include any terminating null 
  80125. character.
  80126.  
  80127.                            Note
  80128.  
  80129. The Script Manager uses a different scheme for handling 
  80130. multibyte characters. See Inside Macintosh, Volume V, for more 
  80131. details on multibyte character handling.
  80132.  
  80133. See also
  80134. local, multibyte character functions
  80135. Inside Macintosh, Volume V
  80136.  
  80137. æKY qsort
  80138. æFc StdLib.h
  80139. æC                           Synopsis
  80140.  
  80141. #include <StdLib.h>
  80142. void qsort(void *base, size_t nmemb, size_t size, int (*compar)
  80143.          (const void *, const void *));
  80144.  
  80145.                            Description
  80146.  
  80147. The qsort; function is an implementation of the quicker-sort 
  80148. algorithm. It sorts a table of data in place.
  80149. The base parameter points to the element at the base of the 
  80150. table. Parameter nmemb is the number of elements in the table. 
  80151. Parameter size is the size of an element in the table; it can be 
  80152. specified as sizeof(*base).
  80153.  
  80154. The compar parameter is a pointer to a comparison function that 
  80155. you supply. The function qsort calls your comparison function 
  80156. with pointers to two elements being compared. Here is a sample 
  80157. prototype for your comparison function:
  80158. int myCompare(char *elem1, char *elem2);
  80159.  
  80160. Your comparison function supplies the result of the 
  80161. comparison to qsort by returning one of the following integer 
  80162. values.
  80163.  
  80164. Result   Meaning
  80165.  
  80166. <0       The first parameter is less than the second parameter.
  80167.  0       The first parameter is equal to the second parameter.
  80168. >0       The first parameter is greater than the second parameter.
  80169.  
  80170.                            Note
  80171.  
  80172. The base parameter, the pointer to the base of the table, should 
  80173. be of type pointer-to-element.
  80174.  
  80175. See also
  80176. bsearch
  80177.  
  80178. æKY rand
  80179. srand
  80180. æFc StdLib.h
  80181. æC                           Synopsis
  80182.  
  80183. #include <StdLib.h>
  80184. int rand(void);
  80185. void srand(unsigned int seed);
  80186.  
  80187.                            Description
  80188.  
  80189. The rand; function uses a multiplicative congruential random-
  80190. number generator with period 232 that returns successive 
  80191. pseudorandom numbers in the range from 0 to 215–1.
  80192.  
  80193. The srand; function can be called at any time to reset the 
  80194. random-number generator to a specific seed. The generator is 
  80195. initially seeded with a value of 1. Identical seeds produce 
  80196. identical sequences of pseudorandom numbers.
  80197.  
  80198. See also
  80199. Inside Macintosh
  80200.  
  80201. æKY strtod
  80202. æFc StdLib.h
  80203. æC                           Synopsis
  80204.  
  80205. #include <StdLib.h>
  80206. double strtod(const char *nptr, char ** endptr);
  80207.  
  80208.                            Description
  80209.  
  80210. The strtod; function returns a double containing the value 
  80211. represented by the character string nptr. The string is scanned 
  80212. up to the first character inconsistent with a floating-point 
  80213. constant. Leading white-space characters are ignored.
  80214. If the value of endptr is not NULL, a pointer to the character 
  80215. terminating the scan is returned in *endptr. If no integer can be 
  80216. formed, *endptr is set to nptr and 0 is returned.
  80217.  
  80218. See also
  80219. atoi, scanf, strtol
  80220.  
  80221. æKY strtol
  80222. strtoul
  80223. æFc StdLib.h
  80224. æC                           Synopsis
  80225.  
  80226. #include <StdLib.h>
  80227. long int strtol(const char *nptr, char **endptr, int base);
  80228. unsigned long int strtoul(const char *nptr, char **endptr, int base);
  80229.  
  80230.                            Description
  80231.  
  80232. The strtol; function returns a long containing the value 
  80233. represented by the character string nptr. The string is scanned 
  80234. up to the first character inconsistent with the base (decimal, 
  80235. hexadecimal, or octal). Leading white-space characters are 
  80236. ignored.
  80237.  
  80238. If the value of endptr is not NULL, a pointer to the character 
  80239. terminating the scan is returned in *endptr. If no integer can be 
  80240. formed, *endptr is set to nptr and 0 is returned.
  80241. If base is 0, the base is determined from the string. If the first 
  80242. character after an optional leading sign is not 0, decimal 
  80243. conversion is done; if the 0 is followed by x or X, hexadecimal 
  80244. conversion is done; otherwise octal conversion is done.
  80245. The function call atol(nptr) is equivalent to
  80246. strtol(str, (char **)NULL, 10)
  80247. The function call atoi(nptr) is equivalent to
  80248. (int) strtol(str, (char **)NULL, 10)
  80249. The strtoul; function is similar to the strtol function, except 
  80250. that strtoul returns an unsigned long value. 
  80251.  
  80252.                            Note
  80253.  
  80254. Overflow conditions are ignored. Apple base conventions ($ for 
  80255. hexadecimal, % for binary) are not supported.
  80256.  
  80257. See also
  80258. atof, atoi, scanf
  80259.  
  80260. æKY abortæ 
  80261. æDT 
  80262. abort (void);
  80263.  
  80264. æKY absæ 
  80265. æDT 
  80266. int myVariable = abs ((int) i);
  80267.  
  80268. æKY labsæ 
  80269. æDT 
  80270. long int myVariable = labs ((long int) j);
  80271.  
  80272. æKY atexitæ 
  80273. æDT 
  80274. int myVariable = atexit((void) (*func)(void));
  80275.  
  80276. æKY atofæ 
  80277. æDT 
  80278. extended myVariable = atof((const char *)nptr);
  80279.  
  80280. æKY atoiæ 
  80281. æDT 
  80282. int myVariable = atoi((const char *)nptr);
  80283.  
  80284. æKY atolæ 
  80285. æDT 
  80286. long int myVariable = atol((const char *)nptr);
  80287.  
  80288. æKY bsearchæ 
  80289. æDT 
  80290. void * myVariable = bsearch((const void *)key, (const void *)base, (size_t) nmemb, (size_t) 
  80291.          size, int (*compar)(const void *, const void *));
  80292.          
  80293. æKY divæ 
  80294. æDT 
  80295. div_t myVariable = div ((int) numer, (int) denom);
  80296.  
  80297. æKY ldivæ 
  80298. æDT 
  80299. ldiv_t myVariable = ldiv ((long int) numer, (long int) denom);
  80300.  
  80301. æKY exitæ 
  80302. æDT 
  80303. exit((int) status);
  80304.  
  80305. æKY getenvæ 
  80306. æDT 
  80307. char * my Variable = getenv((const char *)name);
  80308.  
  80309. æKY mallocæ 
  80310. æDT 
  80311. void * myVariable = malloc ((size_t) size);
  80312.  
  80313. æKY freeæ 
  80314. æDT 
  80315. free ((void *)ptr);
  80316.  
  80317. æKY reallocæ 
  80318. æDT 
  80319. void * myVariable = realloc((void *)ptr, (size_t) size);
  80320.  
  80321. æKY callocæ 
  80322. æDT 
  80323. void * myVariable = calloc((size_t) nmemb, (size_t) size);
  80324.  
  80325. æKY mblenæ 
  80326. æDT 
  80327. int myVariable = mblen ((const char *)s, (size_t) n);
  80328.  
  80329. æKY mbtowcæ 
  80330. æDT 
  80331. int myVariable = mbtowc ((wchar_t *)pwc, (const char *)s, (size_t) n);
  80332.  
  80333. æKY wctombæ 
  80334. æDT 
  80335. int myVariable = wctomb ((char *)s, (wchar_t) wchar);
  80336.  
  80337. æKY mbstowcsæ 
  80338. æDT 
  80339. size_t myVariable = mbstowcs ((wchar_t *)pwcs, (const char *)s, (size_t) n);
  80340.  
  80341. æKY wcstombsæ 
  80342. æDT 
  80343. size_t myVariable = wcstombs ((char *)s, (const wchar_t *)pwcs, (size_t) n);
  80344.  
  80345. æKY qsortæ 
  80346. æDT 
  80347. void myVariable = qsort((void *)base, (size_t) nmemb, (size_t) size, int (*compar)
  80348.          (const void *, const void *));
  80349.          
  80350. æKY srandæ 
  80351. æDT 
  80352. srand((unsigned int) seed);
  80353.  
  80354. æKY strtodæ 
  80355. æDT 
  80356. double myVariable = strtod((const char *)nptr, (char **) endptr);
  80357.  
  80358. æKY strtolæ 
  80359. æDT 
  80360. long int myVariable = strtol((const char *)nptr, (char **)endptr, (int) base);
  80361.  
  80362.  
  80363. æKY strtoulæ 
  80364. æDT 
  80365. unsigned long int myVariable =  strtoul((const char *)nptr, (char **)endptr, (int) base);
  80366.  
  80367. æKY randæ
  80368. æDT 
  80369. void myVariable = srand((unsigned int) seed);
  80370.  
  80371. æKY String.h
  80372. æFc String.h
  80373. æC 
  80374. memccpy    strcat     strerror    strrchr
  80375. memchr     strchr     strlen      strspn
  80376. memcmp     strcmp     strncat     strstr
  80377. memcpy     strcoll    strncmp     strtok
  80378. memmove    strcpy     strncpy     strxfrm
  80379. memset     strcspn    strpbrk     
  80380.  
  80381.                   String Handling
  80382.  
  80383. The Standard C Library provides functions for string 
  80384. operations: copying, concatenation, comparison, searching.
  80385.  
  80386. String function conventions
  80387. The string parameters (srcStr, destStr, and so forth) and s 
  80388. point to arrays of characters terminated by a null character. 
  80389. The functions strcat, strncat, strcpy, and strncpy all alter 
  80390. destStr. These functions do not check for overflow of the array 
  80391. pointed to by destStr.
  80392.  
  80393. Memory operations include the functions memcmp, memcpy, 
  80394. memmove, memchr, and memset. These functions operate efficiently 
  80395. on memory areas (arrays of characters bounded by a count, 
  80396. not terminated by a null character). They do not check for the 
  80397. overflow of any receiving memory area.
  80398. Example
  80399. #include <String.h>
  80400. static char str[] = "#car#//pe,,,?diem";
  80401. char *token;
  80402. token = strtok(str,  "#");       /* token points to "car" */
  80403. token = strtok(NULL, ",");       /* token points to "//pe" */
  80404. token = strtok(NULL, "?");       /* token points to "diem" */
  80405. token = strtok(NULL, "?");       /* token is a null pointer */
  80406.  
  80407. æKY memchr
  80408. strchr
  80409. strrchr
  80410. strpbrk
  80411. strspn
  80412. strcspn
  80413. strstr
  80414. strtok
  80415. æFc String.h
  80416. æC Synopsis
  80417.  
  80418. #include <String.h>
  80419. void *memchr (const void *s, int c, size_t n);
  80420. char *strchr (const char *s, int c);
  80421. char *strrchr (const char *s, int c);
  80422. char *strpbrk (const char *s1, const char *s2);
  80423. size_t strspn (const char *spanChrs, const char *srcStr);
  80424. size_t strcspn (const char *srcStr, const char *s2);
  80425. char *strstr (const char *s1, const char *s2);
  80426. char *strtok (char *destStr, const char *tokenStr);
  80427.  
  80428.                            Description
  80429.  
  80430. The memchr; function looks for the first occurrence of integer 
  80431. c in the first n characters of memory area s.
  80432.  
  80433. The strchr; function looks for the first occurrence of integer 
  80434. c in string s, and the strrchr function looks for the last 
  80435. occurrence of integer c in string s. The null character 
  80436. terminating a string is considered to be part of the string. In 
  80437. previous versions of the Standard C Library, strchr was known 
  80438. as index and strrchr was known as rindex.
  80439.  
  80440. The strpbrk; function looks for the first occurrence in string 
  80441. s1 of any character from string s2.
  80442.  
  80443. The strspn; function determines the length of the initial 
  80444. segment of string srcStr that consists entirely of characters 
  80445. from string spanChars.
  80446.  
  80447. The strcspn; function determines the length of the initial 
  80448. segment of string srcStr that consists entirely of characters not 
  80449. from string s2.
  80450.  
  80451. The strstr; function looks for the first occurence of string s2 
  80452. within s1.
  80453.  
  80454. The strtok; function considers the string destStr as a 
  80455. sequence of zero or more text tokens separated by spans of 
  80456. one or more characters from the separator string tokenStr. The 
  80457. first call (with pointer destStr specified) returns a pointer to 
  80458. the first character of the first token and writes a null character 
  80459. into destStr immediately following the returned token. The 
  80460. function keeps track of its position in the string between calls. 
  80461. Subsequent calls for the same string must be made with a null 
  80462. pointer as the first parameter. The separator string tokenStr 
  80463. may be different from call to call. When no token remains in 
  80464. destStr, a null pointer is returned.
  80465.  
  80466.                            Return values
  80467.  
  80468. The memchr; function returns either a pointer to the first 
  80469. occurrence of integer c in the first n characters of memory area 
  80470. s, or a null pointer if c does not occur.
  80471.  
  80472. The strchr; function returns a pointer to the first occurrence 
  80473. of integer c in string s, and the strrchr function returns a 
  80474. pointer to the last occurrence of integer c in string s. Each of 
  80475. these functions return a null pointer if c does not occur in the 
  80476. string. 
  80477.  
  80478. The strpbrk; function returns a pointer to the first 
  80479. occurrence in string s1 of any character from string s2, or a 
  80480. null pointer if no character from s2 exists in s1.
  80481.  
  80482. The strspn; function returns the length of the initial segment 
  80483. of string srcStr that consists entirely of characters from string 
  80484. spanChars.
  80485.  
  80486. The strcspn; function returns the length of the initial 
  80487. segment of string srcStr that consists entirely of characters not 
  80488. from string s2.
  80489.  
  80490. The strstr; function returns a pointer to the first occurrence 
  80491. of string s2 within s1, or a null pointer if s2 doesn’t occur.
  80492. The strtok; function returns a pointer to the first character 
  80493. of the first token, or  a null pointer if no token remains in 
  80494. destStr.
  80495.  
  80496. Example
  80497. #include <String.h>
  80498. static char str[] = "#car#//pe,,,?diem";
  80499. char *token;
  80500. token = strtok(str, "#");    /* token points to "car" */
  80501. token = strtok(NULL, ",");   /* token points to "//pe" */
  80502. token = strtok(NULL, "?");   /* token points to "diem" */
  80503. token = strtok(NULL, "?");   /* token is a null pointer */
  80504.  
  80505. æKY memcmp
  80506. strcmp
  80507. strncmp
  80508. strcoll
  80509. strxfrm
  80510. æFc String.h
  80511. æC                           Synopsis
  80512.  
  80513. #include <String.h>
  80514. int memcmp (const void *s1, const void *s2, size_t n);
  80515. int strcmp (const char *s1, const char *s2);
  80516. int strncmp (const char *s1, const char *s2, size_t n);
  80517. int strcoll (const char *s1, const char *s2);
  80518. size_t strxfrm (char *s1, const char *s2, size_t n);
  80519.  
  80520.                            Description
  80521.  
  80522. The memcmp; function compares its parameters, s1 and s2, 
  80523. looking at the first n characters only. It returns an integer less 
  80524. than, equal to, or greater than 0, depending on whether s1 is 
  80525. less than, equal to, or greater than s2 in the ASCII collating 
  80526. sequence.
  80527.  
  80528. The strcmp; function performs a comparison of its parameters 
  80529. according to the ASCII collating sequence and returns an 
  80530. integer less than, equal to, or greater than 0 when s1 is less 
  80531. than, equal to, or greater than s2, respectively. The function 
  80532.  
  80533. strncmp makes the same comparison but looks at a maximum of n 
  80534. characters.
  80535.  
  80536. The strcoll; function compares string s1 to string s2 in a 
  80537. locale-specific way. It returns an integer less than, equal to, or 
  80538. greater than 0, depending on whether s1 is less than, equal to, 
  80539. or greater than s2 in the current locale’s collating sequence. 
  80540. Strings s1 and s2 are interpreted according to the LC_COLLATE 
  80541. category in the current locale. (The Toolbox function EqualString 
  80542. gives a similar result.)
  80543.  
  80544. The strxfrm; function transforms a locale-specific string s2 
  80545. into a normal string and  places the result into s1. It returns 
  80546. the length of the transformed string. A maximum of n characters 
  80547. can be placed in s1. If you transform two strings by using 
  80548. strxfrm and then compare them by using strcmp, you will get the 
  80549. same result as if you had compared them (untransformed) by 
  80550. using strcoll.
  80551.  
  80552.                            Return values
  80553.  
  80554. The memcmp;, strcmp, strncmp, and strcoll functions return an 
  80555. integer value representing whether s1 is greater than, less 
  80556. than, or equal to s2. The strxfrm; function returns the length 
  80557. of string s2.
  80558.  
  80559.                            Warning
  80560.  
  80561. The memcmp, strcmp, and strncmp functions use signed arithmetic 
  80562. when comparing their parameters. The sign of the result will be 
  80563. incorrect for characters with values greater than 0x7F in the 
  80564. Macintosh extended character set.
  80565.  
  80566. See also
  80567. locale.h
  80568.  
  80569. æKY memcpy
  80570. memccpy
  80571. memmove
  80572. strcpy
  80573. strncpy
  80574. æFc String.h
  80575. æC                           Synopsis
  80576.  
  80577. #include <String.h>
  80578. void *memcpy (void *dest, const void *source, size_t n);
  80579. void *memccpy (void *dest, const void *source, int c, size_t n);
  80580. void *memmove (void *dest, const void *source, size_t n);
  80581. char *strcpy (char *destStr, const char *srcStr);
  80582. char *strncpy (char *destStr, const char *srcStr, size_t n);
  80583.  
  80584.                            Description
  80585.  
  80586. The memcpy; function copies n characters from memory area 
  80587. source to dest. It returns dest. The function memmove also copies 
  80588. characters from source to dest; it is the same as memcpy except 
  80589. that it can also work on overlapping objects. 
  80590.  
  80591. The memccpy; function copies characters from memory area 
  80592. source into dest, stopping after the first occurrence of integer c 
  80593. has been copied or after n characters have been copied, 
  80594. whichever comes first. It returns either a pointer to the 
  80595. character after the copy of c in dest or a null pointer if c was 
  80596. not found in the first n characters of source.
  80597.  
  80598. The strcpy; function copies string srcStr to string destStr, 
  80599. stopping after the null character has been copied. The function 
  80600.  
  80601. strncpy copies exactly n characters, truncating srcStr or adding 
  80602. null characters to destStr if necessary. The result is not 
  80603. terminated with a null if the length of srcStr is n or more. Each 
  80604. function returns destStr.
  80605.  
  80606.                            Return values
  80607.  
  80608. The memcpy,; memmove, and memccpy functions return the value 
  80609. of dest. The strcpy; and strncpy functions return the value of 
  80610. destStr.
  80611.  
  80612.                            Warning
  80613.  
  80614. Unless otherwise noted, overlapping moves yield unexpected 
  80615. results.  
  80616.  
  80617. æKY memset
  80618. strerror
  80619. strlen
  80620. æFc String.h
  80621. æC Synopsis
  80622.  
  80623. #include <String.h>
  80624. void *memset (void *dest, int c, size_t n);
  80625. char *strerror (int errnum);
  80626. size_t strlen (const char *s);
  80627.  
  80628.                            Description
  80629.  
  80630. The memset; function sets the first n characters in memory 
  80631. area dest to the value of integer c. It returns dest.
  80632.  
  80633. The strerror; function returns an error message 
  80634. corresponding to the error number n. These error messages 
  80635. and their numbers are listed in the section “Errors–ErrNo.h,” 
  80636. earlier in this chapter.
  80637.  
  80638. The strlen; function determines the number of characters in 
  80639. s, not including the terminating null character.
  80640.  
  80641.                            Return values
  80642.  
  80643. The memset; function returns the value of dest. The 
  80644. strerror; function returns a pointer to an error-message 
  80645. string. The strlen; function returns the value of s.
  80646.  
  80647.  
  80648. æKY strcat
  80649. strncat
  80650. æFc String.h
  80651. æC
  80652.                     Synopsis
  80653.  
  80654. #include <String.h>
  80655. char *strcat (char *destStr, const char *srcStr);
  80656. char *strncat (char *destStr, const char *srcStr, size_t n);
  80657.  
  80658.                            Description
  80659.  
  80660. The strcat; function appends a copy of string srcStr to the 
  80661. end of string destStr. The strncat function appends at most n 
  80662. characters. Each function returns a pointer to the null-
  80663. terminated result.
  80664.  
  80665.                            Return values
  80666.  
  80667. The strcat; and strncat functions return the value of destStr.
  80668.  
  80669.  
  80670.  
  80671.  
  80672. æKY memchræ 
  80673. æDT 
  80674. void * myVariable = memchr ((const void *)s, (int) c, (size_t) n);
  80675.  
  80676. æKY strchræ 
  80677. æDT 
  80678. char * myVariable = strchr ((const char *)s, (int) c);
  80679.  
  80680. æKY strrchræ 
  80681. æDT 
  80682. char * myVariable = strrchr ((const char *)s, (int) c);
  80683.  
  80684. æKY strpbrkæ 
  80685. æDT 
  80686. char * myVariable = strpbrk ((const char *)s1, (const char *)s2);
  80687.  
  80688. æKY strspnæ 
  80689. æDT 
  80690. size_t  myVariable = strspn ((const char *)spanChrs, (const char *)srcStr);
  80691.  
  80692.  
  80693. æKY strcspnæ 
  80694. æDT 
  80695. size_t myVariable = strcspn ((const char *)srcStr, (const char *)s2);
  80696.  
  80697. æKY strstræ 
  80698. æDT 
  80699. char * myVariable = strstr ((const char *)s1, (const char *)s2);
  80700.  
  80701. æKY strtokæ 
  80702. æDT 
  80703. char * myVariable = strtok ((char *)destStr, (const char *)tokenStr);
  80704.  
  80705. æKY memcmpæ 
  80706. æDT 
  80707. int myVariable = memcmp ((const void *)s1, (const void *)s2, (size_t) n);
  80708.  
  80709. æKY strcmpæ 
  80710. æDT 
  80711. int myVariable = strcmp ((const char *)s1, (const char *)s2);
  80712.  
  80713.  
  80714. æKY strncmpæ 
  80715. æDT 
  80716. int myVariable = strncmp ((const char *)s1, (const char *)s2, (size_t) n);
  80717.  
  80718. æKY strcollæ 
  80719. æDT 
  80720. int myVariable = strcoll ((const char *)s1, (const char *)s2);
  80721.  
  80722. æKY strxfrmæ 
  80723. æDT 
  80724. size_t myVariable = strxfrm ((char *)s1, (const char *)s2, (size_t) n);
  80725.  
  80726. æKY memcpyæ 
  80727. æDT 
  80728. void * myVariable = memcpy ((void *)dest, (const void *)source, (size_t) n);
  80729.  
  80730. æKY memccpyæ 
  80731. æDT 
  80732. void * myVariable = memccpy ((void *)dest, (const void *)source, (int) c, (size_t) n);
  80733.  
  80734. æKY memmoveæ 
  80735. æDT 
  80736. void * myVariable = memmove ((void *)dest, (const void *)source, (size_t) n);
  80737.  
  80738. æKY strcpyæ 
  80739. æDT 
  80740. char * myVariable = strcpy ((char *)destStr, (const char *)srcStr);
  80741.  
  80742. æKY strncpyæ 
  80743. æDT 
  80744. char * myVariable = strncpy ((char *)destStr, (const char *)srcStr, (size_t) n);
  80745.  
  80746.  
  80747. æKY memsetæ 
  80748. æDT 
  80749. void * myVariable = memset ((void *)dest, (int) c, (size_t) n);
  80750.  
  80751. æKY strerroræ 
  80752. æDT 
  80753. char * myVariable = strerror ((int) errnum);
  80754.  
  80755. æKY strlenæ 
  80756. æDT 
  80757. size_t myVariable = strlen ((const char *)s);
  80758.  
  80759. æKY strcatæ 
  80760. æDT 
  80761. char * myVariable = strcat ((char *)destStr, (const char *)srcStr);
  80762.  
  80763. æKY strncatæ 
  80764. æDT 
  80765. char * myVariable = strncat ((char *)destStr, (const char *)srcStr, (size_t) n);
  80766.  
  80767. æKY Strings.h
  80768. æFc Strings.h
  80769. æKL c2pstr
  80770. p2cstr
  80771.  
  80772. æKY c2pstr
  80773. æFc Strings.h
  80774. æT Function
  80775. æD StringPtr c2pstr(char *aStr);
  80776. æDT StringPtr myVariable = c2pstr((char *)aStr);
  80777.  
  80778.  
  80779. æKY p2cstr
  80780. æFc Strings.h
  80781. æT Function
  80782. æD char *p2cstr(StringPtr aStr);
  80783. æDT char myVariable = p2cstr((StringPtr)aStr);
  80784.  
  80785. æKY SysEqu.h
  80786. æKL 
  80787. ABusDCE
  80788. ABusVars
  80789. ADBBase
  80790. AlarmState
  80791. ApplLimit
  80792. ApplZone
  80793. ASCBase
  80794. BootDrive
  80795. BufPtr
  80796. BufTgDate
  80797. BufTgFBkNum
  80798. BufTgFFlg
  80799. BufTgFNum
  80800. BusErrVct
  80801. CaretTime
  80802. ChunkyDepth
  80803. ColLines
  80804. CommToolboxGlobals
  80805. CPUFlag
  80806. CQDGlobals
  80807. CrsrAddr
  80808. CrsrBase
  80809. CrsrBusy
  80810. CrsrCouple
  80811. CrsrDevice
  80812. CrsrNew
  80813. CrsrObscure
  80814. CrsrPin
  80815. CrsrPtr
  80816. CrsrRect
  80817. CrsrRow
  80818. CrsrSave
  80819. CrsrScale
  80820. CrsrState
  80821. CrsrThresh
  80822. CrsrVis
  80823. CurActivate
  80824. CurApName
  80825. CurApRefNum
  80826. CurDeactive
  80827. CurDirStore
  80828. CurJTOffset
  80829. CurMap
  80830. CurPageOption
  80831. CurPitch
  80832. CurrentA5
  80833. CurStackBase
  80834. DefltStack
  80835. DeskHook
  80836. DeskPattern
  80837. DeviceList
  80838. DoubleTime
  80839. DragHook
  80840. DrvQHdr
  80841. DSAlertRect
  80842. DSAlertTab
  80843. DSCtrAdj
  80844. DSDrawProc
  80845. DSErrCode
  80846. DskErr
  80847. DskVerify
  80848. DSWndUpdate
  80849. DTQFlags
  80850. DTQueue
  80851. DTskQHdr
  80852. DTskQTail
  80853. EjectNotify
  80854. EndSRTPtr
  80855. EventQueue
  80856. EvtBufCnt
  80857. ExpandMem
  80858. ExtStsDT
  80859. GetParam
  80860. GhostWindow
  80861. GrayRgn
  80862. GZMoveHnd
  80863. GZRootHnd
  80864. GZRootPtr
  80865. HeapEnd
  80866. HiHeapMark
  80867. HiKeyLast
  80868. HiliteMode
  80869. HiliteRGB
  80870. HpChk
  80871. IAZNotify
  80872. IconTLAddr
  80873. IntFlag
  80874. IntlSpec
  80875. IWM
  80876. JAllocCrsr
  80877. JCrsrTask
  80878. JDTInstall
  80879. JFetch
  80880. JGNEFilter
  80881. JIODone
  80882. JKybdTask
  80883. JOpcodeProc
  80884. JournalFlag
  80885. JournalRef
  80886. JSetCCrsr
  80887. JStash
  80888. JSwapMMU
  80889. JVBLTask
  80890. KbdLast
  80891. KbdType
  80892. KbdVars
  80893. Key1Trans
  80894. Key2Trans
  80895. KeyLast
  80896. KeyMapLM
  80897. KeyMVars
  80898. KeypadMap
  80899. KeyRepThresh
  80900. KeyRepTime
  80901. KeyThresh
  80902. KeyTime
  80903. LastTxGDevice
  80904. LaunchFlag
  80905. Lo3Bytes
  80906. LoaderPBlock
  80907. LoadTrap
  80908. Lvl1DT
  80909. Lvl2DT
  80910. MainDevice
  80911. MaskBC
  80912. MaskHandle
  80913. MaskPtr
  80914. MBarHeight
  80915. MBState
  80916. MBTicks
  80917. MemErr
  80918. MemTop
  80919. MickeyBytes
  80920. MinStack
  80921. MinusOne
  80922. MMDefFlags
  80923. MmInOK
  80924. MMU32bit
  80925. MMUFlags
  80926. MMUFluff
  80927. MMUTbl
  80928. MMUTblSize
  80929. MMUType
  80930. MonkeyLives
  80931. Mouse
  80932. MouseMask
  80933. MouseOffset
  80934. MTemp
  80935. NewCrsrJTbl
  80936. NMIFlag
  80937. OneOne
  80938. PaintWhite
  80939. PCDeskPat
  80940. PortAUse
  80941. PortBUse
  80942. PortList
  80943. PWMBuf2
  80944. QDColors
  80945. QDErrLM
  80946. QDExist
  80947. RAMBase
  80948. RawMouse
  80949. ResErr
  80950. ResErrProc
  80951. ResLoad
  80952. ResReadOnly
  80953. RestProc
  80954. ResumeProc
  80955. RGBBlack
  80956. RGBWhite
  80957. RndSeed
  80958. ROM85
  80959. ROMBase
  80960. ROMMapHndl
  80961. RomMapInsert
  80962. RowBits
  80963. SaveSegHandle
  80964. SCCASts
  80965. SCCBSts
  80966. SCCRd
  80967. SCCWr
  80968. ScrapCount
  80969. ScrapEnd
  80970. ScrapHandle
  80971. ScrapInfo
  80972. ScrapName
  80973. ScrapSize
  80974. ScrapState
  80975. ScrapTag
  80976. ScrapVars
  80977. Scratch20
  80978. Scratch8
  80979. ScrDmpEnb
  80980. ScrDmpType
  80981. ScreenBytes
  80982. ScreenRow
  80983. ScrHRes
  80984. ScrnBase
  80985. ScrnVBLPtr
  80986. ScrVRes
  80987. SCSIBase
  80988. SCSIDMA
  80989. SCSIGlobals
  80990. SCSIHsk
  80991. SCSIPoll
  80992. SdmBusErr
  80993. SDMJmpTblPtr
  80994. SdVolume
  80995. SegHiEnable
  80996. SerialVars
  80997. SEVarBase
  80998. SEvtEnb
  80999. SFSaveDisk
  81000. SInfoPtr
  81001. SInitFlags
  81002. SlotPrTbl
  81003. SlotQDT
  81004. SlotTICKS
  81005. SlotVBLQ
  81006. SMGlobals
  81007. SoundActive
  81008. SoundBase
  81009. SoundDCE
  81010. SoundLevel
  81011. SoundPtr
  81012. SoundVBL
  81013. SPAlarm
  81014. SPATalkA
  81015. SPATalkB
  81016. SPClikCaret
  81017. SPConfig
  81018. SPFont
  81019. SPKbd
  81020. SPMisc1
  81021. SPMisc2
  81022. SPPortA
  81023. SPPortB
  81024. SPPrint
  81025. SPValid
  81026. SPVolCtl
  81027. SrcDevice
  81028. SRsrcTblPtr
  81029. StkLowPt
  81030. SwitcherTPtr
  81031. SysEvtBuf
  81032. SysEvtMask
  81033. SysMap
  81034. SysMapHndl
  81035. SysParam
  81036. SysResName
  81037. SysVersion
  81038. SysZone
  81039. TableSeed
  81040. TagData
  81041. TEDoText
  81042. TERecal
  81043. TEScrpHandle
  81044. TEScrpLength
  81045. TESysJust
  81046. TEWdBreak
  81047. TheCrsr
  81048. TheGDevice
  81049. TheZone
  81050. Ticks
  81051. TimeDBRA
  81052. TimeLM
  81053. TimeSCCDB
  81054. TimeSCSIDB
  81055. TmpResLoad
  81056. TopMapHndl
  81057. UnitNtryCnt
  81058. UTableBase
  81059. VBLQueue
  81060. VertRRate
  81061. VIA
  81062. VIA2DT
  81063. VideoInfoOK
  81064. VidMode
  81065. VidType
  81066. WarmStart
  81067. WindowList
  81068. WMgrCPort
  81069. WMgrPort
  81070. WordRedraw
  81071. WWExist
  81072.  
  81073. æKY PCDeskPat
  81074. æFc SysEqu.h
  81075. æT #define
  81076. æD #define PCDeskPat 0x20B /*[GLOBAL VAR]  desktop pat, top bit only! others are in use*/
  81077. æC 
  81078.  
  81079. æKY HiKeyLast
  81080. æFc SysEqu.h
  81081. æT #define
  81082. æD #define HiKeyLast 0x216 /*[GLOBAL VAR]  Same as KbdVars*/
  81083. æC 
  81084.  
  81085. æKY KbdLast
  81086. æFc SysEqu.h
  81087. æT #define
  81088. æD #define KbdLast 0x218 /*[GLOBAL VAR]  Same as KbdVars+2*/
  81089. æC 
  81090.  
  81091. æKY ExpandMem
  81092. æFc SysEqu.h
  81093. æT #define
  81094. æD #define ExpandMem 0x2B6 /*[GLOBAL VAR]  pointer to expanded memory block*/
  81095. æC 
  81096.  
  81097. æKY SCSIBase
  81098. æFc SysEqu.h
  81099. æT #define
  81100. æD #define SCSIBase 0x0C00 /*[GLOBAL VAR]  (long) base address for SCSI chip read*/
  81101. æC 
  81102.  
  81103. æKY SCSIDMA
  81104. æFc SysEqu.h
  81105. æT #define
  81106. æD #define SCSIDMA 0x0C04 /*[GLOBAL VAR]  (long) base address for SCSI DMA*/
  81107. æC 
  81108.  
  81109. æKY SCSIHsk
  81110. æFc SysEqu.h
  81111. æT #define
  81112. æD #define SCSIHsk 0x0C08 /*[GLOBAL VAR]  (long) base address for SCSI handshake*/
  81113. æC 
  81114.  
  81115. æKY SCSIGlobals
  81116. æFc SysEqu.h
  81117. æT #define
  81118. æD #define SCSIGlobals 0x0C0C /*[GLOBAL VAR]  (long) ptr for SCSI mgr locals*/
  81119. æC 
  81120.  
  81121. æKY RGBBlack
  81122. æFc SysEqu.h
  81123. æT #define
  81124. æD #define RGBBlack 0x0C10 /*[GLOBAL VAR]  (6 bytes) the black field for color*/
  81125. æC 
  81126.  
  81127. æKY RGBWhite
  81128. æFc SysEqu.h
  81129. æT #define
  81130. æD #define RGBWhite 0x0C16 /*[GLOBAL VAR]  (6 bytes) the white field for color*/
  81131. æC 
  81132.  
  81133. æKY RowBits
  81134. æFc SysEqu.h
  81135. æT #define
  81136. æD #define RowBits 0x0C20 /*[GLOBAL VAR]  (word) screen horizontal pixels*/
  81137. æC 
  81138.  
  81139. æKY ColLines
  81140. æFc SysEqu.h
  81141. æT #define
  81142. æD #define ColLines 0x0C22 /*[GLOBAL VAR]  (word) screen vertical pixels*/
  81143. æC 
  81144.  
  81145. æKY ScreenBytes
  81146. æFc SysEqu.h
  81147. æT #define
  81148. æD #define ScreenBytes 0x0C24 /*[GLOBAL VAR]  (long) total screen bytes*/
  81149. æC 
  81150.  
  81151. æKY NMIFlag
  81152. æFc SysEqu.h
  81153. æT #define
  81154. æD #define NMIFlag 0x0C2C /*[GLOBAL VAR]  (byte) flag for NMI debounce*/
  81155. æC 
  81156.  
  81157. æKY VidType
  81158. æFc SysEqu.h
  81159. æT #define
  81160. æD #define VidType 0x0C2D /*[GLOBAL VAR]  (byte) video board type ID*/
  81161. æC 
  81162.  
  81163. æKY VidMode
  81164. æFc SysEqu.h
  81165. æT #define
  81166. æD #define VidMode 0x0C2E /*[GLOBAL VAR]  (byte) video mode (4=4bit color)*/
  81167. æC 
  81168.  
  81169. æKY SCSIPoll
  81170. æFc SysEqu.h
  81171. æT #define
  81172. æD #define SCSIPoll 0x0C2F /*[GLOBAL VAR]  (byte) poll for device zero only once.*/
  81173. æC 
  81174.  
  81175. æKY SEVarBase
  81176. æFc SysEqu.h
  81177. æT #define
  81178. æD #define SEVarBase 0x0C30 /*[GLOBAL VAR] */
  81179. æC 
  81180.  
  81181. æKY MMUFlags
  81182. æFc SysEqu.h
  81183. æT #define
  81184. æD #define MMUFlags 0x0CB0 /*[GLOBAL VAR]  (byte) cleared to zero (reserved for future use)*/
  81185. æC 
  81186.  
  81187. æKY MMUType
  81188. æFc SysEqu.h
  81189. æT #define
  81190. æD #define MMUType 0x0CB1 /*[GLOBAL VAR]  (byte) kind of MMU present*/
  81191. æC 
  81192.  
  81193. æKY MMU32bit
  81194. æFc SysEqu.h
  81195. æT #define
  81196. æD #define MMU32bit 0x0CB2 /*[GLOBAL VAR]  (byte) boolean reflecting current machine MMU mode*/
  81197. æC 
  81198.  
  81199. æKY MMUFluff
  81200. æFc SysEqu.h
  81201. æT #define
  81202. æD #define MMUFluff 0x0CB3 /*[GLOBAL VAR]  (byte) fluff byte forced by reducing MMUMode to MMU32bit.*/
  81203. æC 
  81204.  
  81205. æKY MMUTbl
  81206. æFc SysEqu.h
  81207. æT #define
  81208. æD #define MMUTbl 0x0CB4 /*[GLOBAL VAR]  (long) pointer to MMU Mapping table*/
  81209. æC 
  81210.  
  81211. æKY MMUTblSize
  81212. æFc SysEqu.h
  81213. æT #define
  81214. æD #define MMUTblSize 0x0CB8 /*[GLOBAL VAR]  (long) size of the MMU mapping table*/
  81215. æC 
  81216.  
  81217. æKY SInfoPtr
  81218. æFc SysEqu.h
  81219. æT #define
  81220. æD #define SInfoPtr 0x0CBC /*[GLOBAL VAR]  (long) pointer to Slot manager information*/
  81221. æC 
  81222.  
  81223. æKY ASCBase
  81224. æFc SysEqu.h
  81225. æT #define
  81226. æD #define ASCBase 0x0CC0 /*[GLOBAL VAR]  (long) pointer to Sound Chip*/
  81227. æC 
  81228.  
  81229. æKY SMGlobals
  81230. æFc SysEqu.h
  81231. æT #define
  81232. æD #define SMGlobals 0x0CC4 /* (long) pointer to Sound Manager Globals*/
  81233. æC 
  81234.  
  81235. æKY TheGDevice
  81236. æFc SysEqu.h
  81237. æT #define
  81238. æD #define TheGDevice 0x0CC8 /*[GLOBAL VAR]  (long) the current graphics device*/
  81239. æC 
  81240.  
  81241. æKY CQDGlobals
  81242. æFc SysEqu.h
  81243. æT #define
  81244. æD #define CQDGlobals 0x0CCC /* (long) quickDraw global extensions*/
  81245. æC 
  81246.  
  81247. æKY ADBBase
  81248. æFc SysEqu.h
  81249. æT #define
  81250. æD #define ADBBase 0x0CF8 /*[GLOBAL VAR]  (long) pointer to Front Desk Buss Variables*/
  81251. æC 
  81252.  
  81253. æKY WarmStart
  81254. æFc SysEqu.h
  81255. æT #define
  81256. æD #define WarmStart 0x0CFC /*[GLOBAL VAR]  (long) flag to indicate it is a warm start*/
  81257. æC 
  81258.  
  81259. æKY TimeDBRA
  81260. æFc SysEqu.h
  81261. æT #define
  81262. æD #define TimeDBRA 0x0D00 /*[GLOBAL VAR]  (word) number of iterations of DBRA per millisecond*/
  81263. æC 
  81264.  
  81265. æKY TimeSCCDB
  81266. æFc SysEqu.h
  81267. æT #define
  81268. æD #define TimeSCCDB 0x0D02 /*[GLOBAL VAR]  (word) number of iter's of SCC access & DBRA.*/
  81269. æC 
  81270.  
  81271. æKY SlotQDT
  81272. æFc SysEqu.h
  81273. æT #define
  81274. æD #define SlotQDT 0x0D04 /*[GLOBAL VAR]  ptr to slot queue table*/
  81275. æC 
  81276.  
  81277. æKY SlotPrTbl
  81278. æFc SysEqu.h
  81279. æT #define
  81280. æD #define SlotPrTbl 0x0D08 /*[GLOBAL VAR]  ptr to slot priority table*/
  81281. æC 
  81282.  
  81283. æKY SlotVBLQ
  81284. æFc SysEqu.h
  81285. æT #define
  81286. æD #define SlotVBLQ 0x0D0C /*[GLOBAL VAR]  ptr to slot VBL queue table*/
  81287. æC 
  81288.  
  81289. æKY ScrnVBLPtr
  81290. æFc SysEqu.h
  81291. æT #define
  81292. æD #define ScrnVBLPtr 0x0D10 /*[GLOBAL VAR]  save for ptr to main screen VBL queue*/
  81293. æC 
  81294.  
  81295. æKY SlotTICKS
  81296. æFc SysEqu.h
  81297. æT #define
  81298. æD #define SlotTICKS 0x0D14 /*[GLOBAL VAR]  ptr to slot tickcount table*/
  81299. æC 
  81300.  
  81301. æKY TableSeed
  81302. æFc SysEqu.h
  81303. æT #define
  81304. æD #define TableSeed 0x0D20 /*[GLOBAL VAR]  (long) seed value for color table ID's*/
  81305. æC 
  81306.  
  81307. æKY SRsrcTblPtr
  81308. æFc SysEqu.h
  81309. æT #define
  81310. æD #define SRsrcTblPtr 0x0D24 /*[GLOBAL VAR]  (long) pointer to slot resource table.*/
  81311. æC 
  81312.  
  81313. æKY JVBLTask
  81314. æFc SysEqu.h
  81315. æT #define
  81316. æD #define JVBLTask 0x0D28 /*[GLOBAL VAR]  vector to slot VBL task interrupt handler*/
  81317. æC 
  81318.  
  81319. æKY WMgrCPort
  81320. æFc SysEqu.h
  81321. æT #define
  81322. æD #define WMgrCPort 0x0D2C /*[GLOBAL VAR]  window manager color port */
  81323. æC 
  81324.  
  81325. æKY VertRRate
  81326. æFc SysEqu.h
  81327. æT #define
  81328. æD #define VertRRate 0x0D30 /*[GLOBAL VAR]  (word) Vertical refresh rate for start manager. */
  81329. æC 
  81330.  
  81331. æKY ChunkyDepth
  81332. æFc SysEqu.h
  81333. æT #define
  81334. æD #define ChunkyDepth 0x0D60 /*[GLOBAL VAR]  depth of the pixels*/
  81335. æC 
  81336.  
  81337. æKY CrsrPtr
  81338. æFc SysEqu.h
  81339. æT #define
  81340. æD #define CrsrPtr 0x0D62 /*[GLOBAL VAR]  pointer to cursor save area*/
  81341. æC 
  81342.  
  81343. æKY PortList
  81344. æFc SysEqu.h
  81345. æT #define
  81346. æD #define PortList 0x0D66 /*[GLOBAL VAR]  list of grafports*/
  81347. æC 
  81348.  
  81349. æKY MickeyBytes
  81350. æFc SysEqu.h
  81351. æT #define
  81352. æD #define MickeyBytes 0x0D6A /*[GLOBAL VAR]  long pointer to cursor stuff*/
  81353. æC 
  81354.  
  81355. æKY QDErrLM
  81356. æFc SysEqu.h
  81357. æT #define
  81358. æD #define QDErrLM 0x0D6E /*[GLOBAL VAR] QDErr has name conflict w/ type. QuickDraw error code [word]*/
  81359. æC 
  81360.  
  81361. æKY VIA2DT
  81362. æFc SysEqu.h
  81363. æT #define
  81364. æD #define VIA2DT 0x0D70 /*[GLOBAL VAR]  32 bytes for VIA2 dispatch table for NuMac*/
  81365. æC 
  81366.  
  81367. æKY SInitFlags
  81368. æFc SysEqu.h
  81369. æT #define
  81370. æD #define SInitFlags 0x0D90 /*[GLOBAL VAR]  StartInit.a flags [word]*/
  81371. æC 
  81372.  
  81373. æKY DTQueue
  81374. æFc SysEqu.h
  81375. æT #define
  81376. æD #define DTQueue 0x0D92 /*[GLOBAL VAR]  (10 bytes) deferred task queue header*/
  81377. æC 
  81378.  
  81379. æKY DTQFlags
  81380. æFc SysEqu.h
  81381. æT #define
  81382. æD #define DTQFlags 0x0D92 /*[GLOBAL VAR]  flag word for DTQueue*/
  81383. æC 
  81384.  
  81385. æKY DTskQHdr
  81386. æFc SysEqu.h
  81387. æT #define
  81388. æD #define DTskQHdr 0x0D94 /*[GLOBAL VAR]  ptr to head of queue*/
  81389. æC 
  81390.  
  81391. æKY DTskQTail
  81392. æFc SysEqu.h
  81393. æT #define
  81394. æD #define DTskQTail 0x0D98 /*[GLOBAL VAR]  ptr to tail of queue*/
  81395. æC 
  81396.  
  81397. æKY JDTInstall
  81398. æFc SysEqu.h
  81399. æT #define
  81400. æD #define JDTInstall 0x0D9C /*[GLOBAL VAR]  (long) ptr to deferred task install routine*/
  81401. æC 
  81402.  
  81403. æKY HiliteRGB
  81404. æFc SysEqu.h
  81405. æT #define
  81406. æD #define HiliteRGB 0x0DA0 /*[GLOBAL VAR]  6 bytes: rgb of hilite color*/
  81407. æC 
  81408.  
  81409. æKY TimeSCSIDB
  81410. æFc SysEqu.h
  81411. æT #define
  81412. æD #define TimeSCSIDB 0x0DA6 /*[GLOBAL VAR]  (word) number of iter's of SCSI access & DBRA*/
  81413. æC 
  81414.  
  81415. æKY DSCtrAdj
  81416. æFc SysEqu.h
  81417. æT #define
  81418. æD #define DSCtrAdj 0x0DA8 /*[GLOBAL VAR]  (long) Center adjust for DS rect.*/
  81419. æC 
  81420.  
  81421. æKY IconTLAddr
  81422. æFc SysEqu.h
  81423. æT #define
  81424. æD #define IconTLAddr 0x0DAC /*[GLOBAL VAR]  (long) pointer to where start icons are to be put.*/
  81425. æC 
  81426.  
  81427. æKY VideoInfoOK
  81428. æFc SysEqu.h
  81429. æT #define
  81430. æD #define VideoInfoOK 0x0DB0 /*[GLOBAL VAR]  (long) Signals to CritErr that the Video card is ok*/
  81431. æC 
  81432.  
  81433. æKY EndSRTPtr
  81434. æFc SysEqu.h
  81435. æT #define
  81436. æD #define EndSRTPtr 0x0DB4 /*[GLOBAL VAR]  (long) Pointer to the end of the Slot Resource Table (Not the SRT buffer).*/
  81437. æC 
  81438.  
  81439. æKY SDMJmpTblPtr
  81440. æFc SysEqu.h
  81441. æT #define
  81442. æD #define SDMJmpTblPtr 0x0DB8 /*[GLOBAL VAR]  (long) Pointer to the SDM jump table*/
  81443. æC 
  81444.  
  81445. æKY JSwapMMU
  81446. æFc SysEqu.h
  81447. æT #define
  81448. æD #define JSwapMMU 0x0DBC /*[GLOBAL VAR]  (long) jump vector to SwapMMU routine*/
  81449. æC 
  81450.  
  81451. æKY SdmBusErr
  81452. æFc SysEqu.h
  81453. æT #define
  81454. æD #define SdmBusErr 0x0DC0 /*[GLOBAL VAR]  (long) Pointer to the SDM busErr handler*/
  81455. æC 
  81456.  
  81457. æKY LastTxGDevice
  81458. æFc SysEqu.h
  81459. æT #define
  81460. æD #define LastTxGDevice 0x0DC4 /*[GLOBAL VAR]  (long) copy of TheGDevice set up for fast text measure*/
  81461. æC 
  81462.  
  81463. æKY NewCrsrJTbl
  81464. æFc SysEqu.h
  81465. æT #define
  81466. æD #define NewCrsrJTbl 0x88C /*[GLOBAL VAR]  location of new crsr jump vectors*/
  81467. æC 
  81468.  
  81469. æKY JAllocCrsr
  81470. æFc SysEqu.h
  81471. æT #define
  81472. æD #define JAllocCrsr 0x88C /*[GLOBAL VAR]  (long) vector to routine that allocates cursor*/
  81473. æC 
  81474.  
  81475. æKY JSetCCrsr
  81476. æFc SysEqu.h
  81477. æT #define
  81478. æD #define JSetCCrsr 0x890 /*[GLOBAL VAR]  (long) vector to routine that sets color cursor*/
  81479. æC 
  81480.  
  81481. æKY JOpcodeProc
  81482. æFc SysEqu.h
  81483. æT #define
  81484. æD #define JOpcodeProc 0x894 /*[GLOBAL VAR]  (long) vector to process new picture opcodes*/
  81485. æC 
  81486.  
  81487. æKY CrsrBase
  81488. æFc SysEqu.h
  81489. æT #define
  81490. æD #define CrsrBase 0x898 /*[GLOBAL VAR]  (long) scrnBase for cursor*/
  81491. æC 
  81492.  
  81493. æKY CrsrDevice
  81494. æFc SysEqu.h
  81495. æT #define
  81496. æD #define CrsrDevice 0x89C /*[GLOBAL VAR]  (long) current cursor device*/
  81497. æC 
  81498.  
  81499. æKY SrcDevice
  81500. æFc SysEqu.h
  81501. æT #define
  81502. æD #define SrcDevice 0x8A0 /*[GLOBAL VAR]  (LONG) Src device for Stretchbits*/
  81503. æC 
  81504.  
  81505. æKY MainDevice
  81506. æFc SysEqu.h
  81507. æT #define
  81508. æD #define MainDevice 0x8A4 /*[GLOBAL VAR]  (long) the main screen device*/
  81509. æC 
  81510.  
  81511. æKY DeviceList
  81512. æFc SysEqu.h
  81513. æT #define
  81514. æD #define DeviceList 0x8A8 /*[GLOBAL VAR]  (long) list of display devices*/
  81515. æC 
  81516.  
  81517. æKY CrsrRow
  81518. æFc SysEqu.h
  81519. æT #define
  81520. æD #define CrsrRow 0x8AC /*[GLOBAL VAR]  (word) rowbytes for current cursor screen*/
  81521. æC 
  81522.  
  81523. æKY QDColors
  81524. æFc SysEqu.h
  81525. æT #define
  81526. æD #define QDColors 0x8B0 /*[GLOBAL VAR]  (long) handle to default colors*/
  81527. æC 
  81528.  
  81529. æKY HiliteMode
  81530. æFc SysEqu.h
  81531. æT #define
  81532. æD #define HiliteMode 0x938 /*[GLOBAL VAR]  used for color highlighting*/
  81533. æC 
  81534.  
  81535. æKY BusErrVct
  81536. æFc SysEqu.h
  81537. æT #define
  81538. æD #define BusErrVct 0x08 /*[GLOBAL VAR]  bus error vector*/
  81539. æC 
  81540.  
  81541. æKY RestProc
  81542. æFc SysEqu.h
  81543. æT #define
  81544. æD #define RestProc 0xA8C /*[GLOBAL VAR]  Resume procedure f InitDialogs [pointer]*/
  81545. æC 
  81546.  
  81547. æKY ROM85
  81548. æFc SysEqu.h
  81549. æT #define
  81550. æD #define ROM85 0x28E /*[GLOBAL VAR]  (word) actually high bit - 0 for ROM vers $75 (sic) and later*/
  81551. æC 
  81552.  
  81553. æKY ROMMapHndl
  81554. æFc SysEqu.h
  81555. æT #define
  81556. æD #define ROMMapHndl 0xB06 /*[GLOBAL VAR]  (long) handle of ROM resource map*/
  81557. æC 
  81558.  
  81559. æKY ScrVRes
  81560. æFc SysEqu.h
  81561. æT #define
  81562. æD #define ScrVRes 0x102 /*[GLOBAL VAR] Pixels per inch vertically (word)
  81563.    screen vertical dots/inch [word]*/
  81564. æC 
  81565.  
  81566. æKY ScrHRes
  81567. æFc SysEqu.h
  81568. æT #define
  81569. æD #define ScrHRes 0x104 /*[GLOBAL VAR] Pixels per inch horizontally (word)
  81570.    screen horizontal dots/inch [word]*/
  81571. æC 
  81572.  
  81573. æKY ScrnBase
  81574. æFc SysEqu.h
  81575. æT #define
  81576. æD #define ScrnBase 0x824 /*[GLOBAL VAR] Address of main screen buffer
  81577.    Screen Base [pointer]*/
  81578. æC 
  81579.  
  81580. æKY ScreenRow
  81581. æFc SysEqu.h
  81582. æT #define
  81583. æD #define ScreenRow 0x106 /*[GLOBAL VAR]  rowBytes of screen [word]*/
  81584. æC 
  81585.  
  81586. æKY MBTicks
  81587. æFc SysEqu.h
  81588. æT #define
  81589. æD #define MBTicks 0x16E /*[GLOBAL VAR]  tick count @ last mouse button [long]*/
  81590. æC 
  81591.  
  81592. æKY JKybdTask
  81593. æFc SysEqu.h
  81594. æT #define
  81595. æD #define JKybdTask 0x21A /*[GLOBAL VAR]  keyboard VBL task hook [pointer]*/
  81596. æC 
  81597.  
  81598. æKY KeyLast
  81599. æFc SysEqu.h
  81600. æT #define
  81601. æD #define KeyLast 0x184 /*[GLOBAL VAR]  ASCII for last valid keycode [word]*/
  81602. æC 
  81603.  
  81604. æKY KeyTime
  81605. æFc SysEqu.h
  81606. æT #define
  81607. æD #define KeyTime 0x186 /*[GLOBAL VAR]  tickcount when KEYLAST was rec'd [long]*/
  81608. æC 
  81609.  
  81610. æKY KeyRepTime
  81611. æFc SysEqu.h
  81612. æT #define
  81613. æD #define KeyRepTime 0x18A /*[GLOBAL VAR]  tickcount when key was last repeated [long]*/
  81614. æC 
  81615.  
  81616. æKY SPConfig
  81617. æFc SysEqu.h
  81618. æT #define
  81619. æD #define SPConfig 0x1FB /*[GLOBAL VAR] Use types for serial ports (byte)
  81620.    config bits: 4-7 A, 0-3 B (see use type below)*/
  81621. æC 
  81622.  
  81623. æKY SPPortA
  81624. æFc SysEqu.h
  81625. æT #define
  81626. æD #define SPPortA 0x1FC /*[GLOBAL VAR] Modem port configuration (word)
  81627.    SCC port A configuration [word]*/
  81628. æC 
  81629.  
  81630. æKY SPPortB
  81631. æFc SysEqu.h
  81632. æT #define
  81633. æD #define SPPortB 0x1FE /*[GLOBAL VAR] Printer port configuration (word)
  81634.    SCC port B configuration [word]*/
  81635. æC 
  81636.  
  81637. æKY SCCRd
  81638. æFc SysEqu.h
  81639. æT #define
  81640. æD #define SCCRd 0x1D8 /*[GLOBAL VAR] SCC read base address
  81641.    SCC base read address [pointer]*/
  81642. æC 
  81643.  
  81644. æKY SCCWr
  81645. æFc SysEqu.h
  81646. æT #define
  81647. æD #define SCCWr 0x1DC /*[GLOBAL VAR] SCC write base address
  81648.    SCC base write address [pointer]*/
  81649. æC 
  81650.  
  81651. æKY DoubleTime
  81652. æFc SysEqu.h
  81653. æT #define
  81654. æD #define DoubleTime 0x2F0 /*[GLOBAL VAR] Double-click interval in ticks (long)
  81655.    double click ticks [long]*/
  81656. æC 
  81657.  
  81658. æKY CaretTime
  81659. æFc SysEqu.h
  81660. æT #define
  81661. æD #define CaretTime 0x2F4 /*[GLOBAL VAR] Caret-blink interval in ticks (long)
  81662.    caret blink ticks [long]*/
  81663. æC 
  81664.  
  81665. æKY KeyThresh
  81666. æFc SysEqu.h
  81667. æT #define
  81668. æD #define KeyThresh 0x18E /*[GLOBAL VAR] Auto-key threshold (word)
  81669.    threshold for key repeat [word]*/
  81670. æC 
  81671.  
  81672. æKY KeyRepThresh
  81673. æFc SysEqu.h
  81674. æT #define
  81675. æD #define KeyRepThresh 0x190 /*[GLOBAL VAR] Auto-key rate (word)
  81676.    key repeat speed [word]*/
  81677. æC 
  81678.  
  81679. æKY SdVolume
  81680. æFc SysEqu.h
  81681. æT #define
  81682. æD #define SdVolume 0x260 /*[GLOBAL VAR] Current speaker volume (byte:  low-order three bits only)
  81683.    Global volume(sound) control [byte]*/
  81684. æC 
  81685.  
  81686. æKY Ticks
  81687. æFc SysEqu.h
  81688. æT #define
  81689. æD #define Ticks 0x16A /*[GLOBAL VAR] Current number of ticks since system startup (long)
  81690.    Tick count, time since boot [unsigned long]*/
  81691. æC 
  81692.  
  81693. æKY TimeLM
  81694. æFc SysEqu.h
  81695. æT #define
  81696. æD #define TimeLM 0x20C /*[GLOBAL VAR] Time has name conflict w/ type. Clock time (extrapolated) [long]*/
  81697. æC 
  81698.  
  81699. æKY MonkeyLives
  81700. æFc SysEqu.h
  81701. æT #define
  81702. æD #define MonkeyLives 0x100 /*[GLOBAL VAR]  monkey lives if >= 0 [word]*/
  81703. æC 
  81704.  
  81705. æKY SEvtEnb
  81706. æFc SysEqu.h
  81707. æT #define
  81708. æD #define SEvtEnb 0x15C /*[GLOBAL VAR] 0 if SystemEvent should return FALSE (byte)
  81709.    enable SysEvent calls from GNE [byte]*/
  81710. æC 
  81711.  
  81712. æKY JournalFlag
  81713. æFc SysEqu.h
  81714. æT #define
  81715. æD #define JournalFlag 0x8DE /*[GLOBAL VAR] Journaling mode (word)
  81716.    journaling state [word]*/
  81717. æC 
  81718.  
  81719. æKY JournalRef
  81720. æFc SysEqu.h
  81721. æT #define
  81722. æD #define JournalRef 0x8E8 /*[GLOBAL VAR] Reference number of journaling device driver (word)
  81723.    Journalling driver's refnum [word]*/
  81724. æC 
  81725.  
  81726. æKY BufPtr
  81727. æFc SysEqu.h
  81728. æT #define
  81729. æD #define BufPtr 0x10C /*[GLOBAL VAR] Address of end of jump table
  81730.    top of application memory [pointer]*/
  81731. æC 
  81732.  
  81733. æKY StkLowPt
  81734. æFc SysEqu.h
  81735. æT #define
  81736. æD #define StkLowPt 0x110 /*[GLOBAL VAR]  Lowest stack as measured in VBL task [pointer]*/
  81737. æC 
  81738.  
  81739. æKY TheZone
  81740. æFc SysEqu.h
  81741. æT #define
  81742. æD #define TheZone 0x118 /*[GLOBAL VAR] Address of current heap zone
  81743.    current heap zone [pointer]*/
  81744. æC 
  81745.  
  81746. æKY ApplLimit
  81747. æFc SysEqu.h
  81748. æT #define
  81749. æD #define ApplLimit 0x130 /*[GLOBAL VAR] Application heap limit
  81750.    application limit [pointer]*/
  81751. æC 
  81752.  
  81753. æKY SysZone
  81754. æFc SysEqu.h
  81755. æT #define
  81756. æD #define SysZone 0x2A6 /*[GLOBAL VAR] Address of system heap zone
  81757.    system heap zone [pointer]*/
  81758. æC 
  81759.  
  81760. æKY ApplZone
  81761. æFc SysEqu.h
  81762. æT #define
  81763. æD #define ApplZone 0x2AA /*[GLOBAL VAR] Address of application heap zone
  81764.    application heap zone [pointer]*/
  81765. æC 
  81766.  
  81767. æKY HeapEnd
  81768. æFc SysEqu.h
  81769. æT #define
  81770. æD #define HeapEnd 0x114 /*[GLOBAL VAR] Address of end of application heap zone
  81771.    end of heap [pointer]*/
  81772. æC 
  81773.  
  81774. æKY HiHeapMark
  81775. æFc SysEqu.h
  81776. æT #define
  81777. æD #define HiHeapMark 0xBAE /*[GLOBAL VAR]  (long) highest address used by a zone below sp<01Nov85 JTC>*/
  81778. æC 
  81779.  
  81780. æKY MemErr
  81781. æFc SysEqu.h
  81782. æT #define
  81783. æD #define MemErr 0x220 /*[GLOBAL VAR]  last memory manager error [word]*/
  81784. æC 
  81785.  
  81786. æKY UTableBase
  81787. æFc SysEqu.h
  81788. æT #define
  81789. æD #define UTableBase 0x11C /*[GLOBAL VAR] Base address of unit table
  81790.    unit I/O table [pointer]*/
  81791. æC 
  81792.  
  81793. æKY UnitNtryCnt
  81794. æFc SysEqu.h
  81795. æT #define
  81796. æD #define UnitNtryCnt 0x1D2 /*[GLOBAL VAR]  count of entries in unit table [word]*/
  81797. æC 
  81798.  
  81799. æKY JFetch
  81800. æFc SysEqu.h
  81801. æT #define
  81802. æD #define JFetch 0x8F4 /*[GLOBAL VAR] Jump vector for Fetch function
  81803.    fetch a byte routine for drivers [pointer]*/
  81804. æC 
  81805.  
  81806. æKY JStash
  81807. æFc SysEqu.h
  81808. æT #define
  81809. æD #define JStash 0x8F8 /*[GLOBAL VAR] Jump vector for Stash function
  81810.    stash a byte routine for drivers [pointer]*/
  81811. æC 
  81812.  
  81813. æKY JIODone
  81814. æFc SysEqu.h
  81815. æT #define
  81816. æD #define JIODone 0x8FC /*[GLOBAL VAR] Jump vector for IODone function
  81817.    IODone entry location [pointer]*/
  81818. æC 
  81819.  
  81820. æKY DrvQHdr
  81821. æFc SysEqu.h
  81822. æT #define
  81823. æD #define DrvQHdr 0x308 /*[GLOBAL VAR] Drive queue header (10 bytes)
  81824.    queue header of drives in system [10 bytes]*/
  81825. æC 
  81826.  
  81827. æKY BootDrive
  81828. æFc SysEqu.h
  81829. æT #define
  81830. æD #define BootDrive 0x210 /*[GLOBAL VAR]  drive number of boot drive [word]*/
  81831. æC 
  81832.  
  81833. æKY EjectNotify
  81834. æFc SysEqu.h
  81835. æT #define
  81836. æD #define EjectNotify 0x338 /*[GLOBAL VAR]  eject notify procedure [pointer]*/
  81837. æC 
  81838.  
  81839. æKY IAZNotify
  81840. æFc SysEqu.h
  81841. æT #define
  81842. æD #define IAZNotify 0x33C /*[GLOBAL VAR]  world swaps notify procedure [pointer]*/
  81843. æC 
  81844.  
  81845. æKY SFSaveDisk
  81846. æFc SysEqu.h
  81847. æT #define
  81848. æD #define SFSaveDisk 0x214 /*[GLOBAL VAR] Negative of volume reference number used by Standard File Package (word)
  81849.    last vRefNum seen by standard file [word]*/
  81850. æC 
  81851.  
  81852. æKY CurDirStore
  81853. æFc SysEqu.h
  81854. æT #define
  81855. æD #define CurDirStore 0x398 /*[GLOBAL VAR]  save dir across calls to Standard File [long]*/
  81856. æC 
  81857.  
  81858. æKY OneOne
  81859. æFc SysEqu.h
  81860. æT #define
  81861. æD #define OneOne 0xA02 /*[GLOBAL VAR] $00010001
  81862.    constant $00010001 [long]*/
  81863. æC 
  81864.  
  81865. æKY MinusOne
  81866. æFc SysEqu.h
  81867. æT #define
  81868. æD #define MinusOne 0xA06 /*[GLOBAL VAR] $FFFFFFFF
  81869.    constant $FFFFFFFF [long]*/
  81870. æC 
  81871.  
  81872. æKY Lo3Bytes
  81873. æFc SysEqu.h
  81874. æT #define
  81875. æD #define Lo3Bytes 0x31A /*[GLOBAL VAR] $00FFFFFF
  81876.    constant $00FFFFFF [long]*/
  81877. æC 
  81878.  
  81879. æKY ROMBase
  81880. æFc SysEqu.h
  81881. æT #define
  81882. æD #define ROMBase 0x2AE /*[GLOBAL VAR] Base address of ROM
  81883.    ROM base address [pointer]*/
  81884. æC 
  81885.  
  81886. æKY RAMBase
  81887. æFc SysEqu.h
  81888. æT #define
  81889. æD #define RAMBase 0x2B2 /*[GLOBAL VAR] Trap dispatch table's base address for routines in RAM
  81890.    RAM base address [pointer]*/
  81891. æC 
  81892.  
  81893. æKY SysVersion
  81894. æFc SysEqu.h
  81895. æT #define
  81896. æD #define SysVersion 0x15A /*[GLOBAL VAR]  version # of RAM-based system [word]*/
  81897. æC 
  81898.  
  81899. æKY RndSeed
  81900. æFc SysEqu.h
  81901. æT #define
  81902. æD #define RndSeed 0x156 /*[GLOBAL VAR] Random number seed (long)
  81903.    random seed/number [long]*/
  81904. æC 
  81905.  
  81906. æKY Scratch20
  81907. æFc SysEqu.h
  81908. æT #define
  81909. æD #define Scratch20 0x1E4 /*[GLOBAL VAR] 20-byte scratch area
  81910.    scratch [20 bytes]*/
  81911. æC 
  81912.  
  81913. æKY Scratch8
  81914. æFc SysEqu.h
  81915. æT #define
  81916. æD #define Scratch8 0x9FA /*[GLOBAL VAR] 8-byte scratch area
  81917.    scratch [8 bytes]*/
  81918. æC 
  81919.  
  81920. æKY ScrapSize
  81921. æFc SysEqu.h
  81922. æT #define
  81923. æD #define ScrapSize 0x960 /*[GLOBAL VAR] Size in bytes of desk scrap (long)
  81924.    scrap length [long]*/
  81925. æC 
  81926.  
  81927. æKY ScrapHandle
  81928. æFc SysEqu.h
  81929. æT #define
  81930. æD #define ScrapHandle 0x964 /*[GLOBAL VAR] Handle to desk scrap in memory
  81931.    memory scrap [handle]*/
  81932. æC 
  81933.  
  81934. æKY ScrapCount
  81935. æFc SysEqu.h
  81936. æT #define
  81937. æD #define ScrapCount 0x968 /*[GLOBAL VAR] Count changed by ZeroScrap (word)
  81938.    validation byte [word]*/
  81939. æC 
  81940.  
  81941. æKY ScrapState
  81942. æFc SysEqu.h
  81943. æT #define
  81944. æD #define ScrapState 0x96A /*[GLOBAL VAR] Tells where desk scrap is (word)
  81945.    scrap state [word]*/
  81946. æC 
  81947.  
  81948. æKY ScrapName
  81949. æFc SysEqu.h
  81950. æT #define
  81951. æD #define ScrapName 0x96C /*[GLOBAL VAR] Pointer to scrap file name (preceded by length byte)
  81952.    pointer to scrap name [pointer]*/
  81953. æC 
  81954.  
  81955. æKY IntlSpec
  81956. æFc SysEqu.h
  81957. æT #define
  81958. æD #define IntlSpec 0xBA0 /*[GLOBAL VAR]  (long) - ptr to extra Intl data */
  81959. æC 
  81960.  
  81961. æKY SwitcherTPtr
  81962. æFc SysEqu.h
  81963. æT #define
  81964. æD #define SwitcherTPtr 0x286 /*[GLOBAL VAR]  Switcher's switch table */
  81965. æC 
  81966.  
  81967. æKY CPUFlag
  81968. æFc SysEqu.h
  81969. æT #define
  81970. æD #define CPUFlag 0x12F /*[GLOBAL VAR]  $00=68000, $01=68010, $02=68020 (old ROM inits to $00)*/
  81971. æC 
  81972.  
  81973. æKY VIA
  81974. æFc SysEqu.h
  81975. æT #define
  81976. æD #define VIA 0x1D4 /*[GLOBAL VAR] VIA base address
  81977.    VIA base address [pointer]*/
  81978. æC 
  81979.  
  81980. æKY IWM
  81981. æFc SysEqu.h
  81982. æT #define
  81983. æD #define IWM 0x1E0 /*[GLOBAL VAR]  IWM base address [pointer]*/
  81984. æC 
  81985.  
  81986. æKY Lvl1DT
  81987. æFc SysEqu.h
  81988. æT #define
  81989. æD #define Lvl1DT 0x192 /*[GLOBAL VAR] Level-1 secondary interrupt vector table (32 bytes)
  81990.    Interrupt level 1 dispatch table [32 bytes]*/
  81991. æC 
  81992.  
  81993. æKY Lvl2DT
  81994. æFc SysEqu.h
  81995. æT #define
  81996. æD #define Lvl2DT 0x1B2 /*[GLOBAL VAR] Level-2 secondary interrupt vector table (32 bytes)
  81997.    Interrupt level 2 dispatch table [32 bytes]*/
  81998. æC 
  81999.  
  82000. æKY ExtStsDT
  82001. æFc SysEqu.h
  82002. æT #define
  82003. æD #define ExtStsDT 0x2BE /*[GLOBAL VAR] External/status interrupt vector table (16 bytes)
  82004.    SCC ext/sts secondary dispatch table [16 bytes]*/
  82005. æC 
  82006.  
  82007. æKY SPValid
  82008. æFc SysEqu.h
  82009. æT #define
  82010. æD #define SPValid 0x1F8 /*[GLOBAL VAR] Validity status (byte)
  82011.    validation field ($A7) [byte]*/
  82012. æC 
  82013.  
  82014. æKY SPATalkA
  82015. æFc SysEqu.h
  82016. æT #define
  82017. æD #define SPATalkA 0x1F9 /*[GLOBAL VAR] AppleTalk node ID hint for modem port (byte)
  82018.    AppleTalk node number hint for port A*/
  82019. æC 
  82020.  
  82021. æKY SPATalkB
  82022. æFc SysEqu.h
  82023. æT #define
  82024. æD #define SPATalkB 0x1FA /*[GLOBAL VAR] AppleTalk node ID hint for printer port (byte)
  82025.    AppleTalk node number hint for port B*/
  82026. æC 
  82027.  
  82028. æKY SPAlarm
  82029. æFc SysEqu.h
  82030. æT #define
  82031. æD #define SPAlarm 0x200 /*[GLOBAL VAR] Alarm setting (long)
  82032.    alarm time [long]*/
  82033. æC 
  82034.  
  82035. æKY SPFont
  82036. æFc SysEqu.h
  82037. æT #define
  82038. æD #define SPFont 0x204 /*[GLOBAL VAR] Application font number minus 1 (word)
  82039.    default application font number minus 1 [word]*/
  82040. æC 
  82041.  
  82042. æKY SPKbd
  82043. æFc SysEqu.h
  82044. æT #define
  82045. æD #define SPKbd 0x206 /*[GLOBAL VAR] Auto-key threshold and rate (byte)
  82046.    kbd repeat thresh in 4/60ths [2 4-bit]*/
  82047. æC 
  82048.  
  82049. æKY SPPrint
  82050. æFc SysEqu.h
  82051. æT #define
  82052. æD #define SPPrint 0x207 /*[GLOBAL VAR] Printer connection (byte)
  82053.    print stuff [byte]*/
  82054. æC 
  82055.  
  82056. æKY SPVolCtl
  82057. æFc SysEqu.h
  82058. æT #define
  82059. æD #define SPVolCtl 0x208 /*[GLOBAL VAR] Speaker volume setting in parameter RAM (byte)
  82060.    volume control [byte]*/
  82061. æC 
  82062.  
  82063. æKY SPClikCaret
  82064. æFc SysEqu.h
  82065. æT #define
  82066. æD #define SPClikCaret 0x209 /*[GLOBAL VAR] Double-click and caret-blink times (byte)
  82067.    double click/caret time in 4/60ths[2 4-bit]*/
  82068. æC 
  82069.  
  82070. æKY SPMisc1
  82071. æFc SysEqu.h
  82072. æT #define
  82073. æD #define SPMisc1 0x20A /*[GLOBAL VAR]  miscellaneous [1 byte]*/
  82074. æC 
  82075.  
  82076. æKY SPMisc2
  82077. æFc SysEqu.h
  82078. æT #define
  82079. æD #define SPMisc2 0x20B /*[GLOBAL VAR] Mouse scaling, system startup disk, menu blink (byte)
  82080.    miscellaneous [1 byte]*/
  82081. æC 
  82082.  
  82083. æKY GetParam
  82084. æFc SysEqu.h
  82085. æT #define
  82086. æD #define GetParam 0x1E4 /*[GLOBAL VAR]  system parameter scratch [20 bytes]*/
  82087. æC 
  82088.  
  82089. æKY SysParam
  82090. æFc SysEqu.h
  82091. æT #define
  82092. æD #define SysParam 0x1F8 /*[GLOBAL VAR] Low-memory copy of parameter RAM (20 bytes)
  82093.    system parameter memory [20 bytes]*/
  82094. æC 
  82095.  
  82096. æKY CrsrThresh
  82097. æFc SysEqu.h
  82098. æT #define
  82099. æD #define CrsrThresh 0x8EC /*[GLOBAL VAR] Mouse-scaling threshold (word) 
  82100.    delta threshold for mouse scaling [word]*/
  82101. æC 
  82102.  
  82103. æKY JCrsrTask
  82104. æFc SysEqu.h
  82105. æT #define
  82106. æD #define JCrsrTask 0x8EE /*[GLOBAL VAR]  address of CrsrVBLTask [long]*/
  82107. æC 
  82108.  
  82109. æKY MTemp
  82110. æFc SysEqu.h
  82111. æT #define
  82112. æD #define MTemp 0x828 /*[GLOBAL VAR]  Low-level interrupt mouse location [long]*/
  82113. æC 
  82114.  
  82115. æKY RawMouse
  82116. æFc SysEqu.h
  82117. æT #define
  82118. æD #define RawMouse 0x82C /*[GLOBAL VAR]  un-jerked mouse coordinates [long]*/
  82119. æC 
  82120.  
  82121. æKY CrsrRect
  82122. æFc SysEqu.h
  82123. æT #define
  82124. æD #define CrsrRect 0x83C /*[GLOBAL VAR]  Cursor hit rectangle [8 bytes]*/
  82125. æC 
  82126.  
  82127. æKY TheCrsr
  82128. æFc SysEqu.h
  82129. æT #define
  82130. æD #define TheCrsr 0x844 /*[GLOBAL VAR]  Cursor data, mask & hotspot [68 bytes]*/
  82131. æC 
  82132.  
  82133. æKY CrsrAddr
  82134. æFc SysEqu.h
  82135. æT #define
  82136. æD #define CrsrAddr 0x888 /*[GLOBAL VAR]  Address of data under cursor [long]*/
  82137. æC 
  82138.  
  82139. æKY CrsrSave
  82140. æFc SysEqu.h
  82141. æT #define
  82142. æD #define CrsrSave 0x88C /*[GLOBAL VAR]  data under the cursor [64 bytes]*/
  82143. æC 
  82144.  
  82145. æKY CrsrVis
  82146. æFc SysEqu.h
  82147. æT #define
  82148. æD #define CrsrVis 0x8CC /*[GLOBAL VAR]  Cursor visible? [byte]*/
  82149. æC 
  82150.  
  82151. æKY CrsrBusy
  82152. æFc SysEqu.h
  82153. æT #define
  82154. æD #define CrsrBusy 0x8CD /*[GLOBAL VAR]  Cursor locked out? [byte]*/
  82155. æC 
  82156.  
  82157. æKY CrsrNew
  82158. æFc SysEqu.h
  82159. æT #define
  82160. æD #define CrsrNew 0x8CE /*[GLOBAL VAR]  Cursor changed? [byte]*/
  82161. æC 
  82162.  
  82163. æKY CrsrState
  82164. æFc SysEqu.h
  82165. æT #define
  82166. æD #define CrsrState 0x8D0 /*[GLOBAL VAR]  Cursor nesting level [word]*/
  82167. æC 
  82168.  
  82169. æKY CrsrObscure
  82170. æFc SysEqu.h
  82171. æT #define
  82172. æD #define CrsrObscure 0x8D2 /*[GLOBAL VAR]  Cursor obscure semaphore [byte]*/
  82173. æC 
  82174.  
  82175. æKY KbdVars
  82176. æFc SysEqu.h
  82177. æT #define
  82178. æD #define KbdVars 0x216 /*[GLOBAL VAR]  Keyboard manager variables [4 bytes]*/
  82179. æC 
  82180.  
  82181. æKY KbdType
  82182. æFc SysEqu.h
  82183. æT #define
  82184. æD #define KbdType 0x21E /*[GLOBAL VAR]  keyboard model number [byte]*/
  82185. æC 
  82186.  
  82187. æKY MBState
  82188. æFc SysEqu.h
  82189. æT #define
  82190. æD #define MBState 0x172 /*[GLOBAL VAR]  current mouse button state [byte]*/
  82191. æC 
  82192.  
  82193. æKY KeyMapLM
  82194. æFc SysEqu.h
  82195. æT #define
  82196. æD #define KeyMapLM 0x174 /*[GLOBAL VAR] KeyMap has name conflict w/ type. Bitmap of the keyboard [4 longs]*/
  82197. æC 
  82198.  
  82199. æKY KeypadMap
  82200. æFc SysEqu.h
  82201. æT #define
  82202. æD #define KeypadMap 0x17C /*[GLOBAL VAR]  bitmap for numeric pad-18bits [long]*/
  82203. æC 
  82204.  
  82205. æKY Key1Trans
  82206. æFc SysEqu.h
  82207. æT #define
  82208. æD #define Key1Trans 0x29E /*[GLOBAL VAR]  keyboard translator procedure [pointer]*/
  82209. æC 
  82210.  
  82211. æKY Key2Trans
  82212. æFc SysEqu.h
  82213. æT #define
  82214. æD #define Key2Trans 0x2A2 /*[GLOBAL VAR]  numeric keypad translator procedure [pointer]*/
  82215. æC 
  82216.  
  82217. æKY JGNEFilter
  82218. æFc SysEqu.h
  82219. æT #define
  82220. æD #define JGNEFilter 0x29A /*[GLOBAL VAR]  GetNextEvent filter proc [pointer]*/
  82221. æC 
  82222.  
  82223. æKY KeyMVars
  82224. æFc SysEqu.h
  82225. æT #define
  82226. æD #define KeyMVars 0xB04 /*[GLOBAL VAR]  (word) for ROM KEYM proc state*/
  82227. æC 
  82228.  
  82229. æKY Mouse
  82230. æFc SysEqu.h
  82231. æT #define
  82232. æD #define Mouse 0x830 /*[GLOBAL VAR]  processed mouse coordinate [long]*/
  82233. æC 
  82234.  
  82235. æKY CrsrPin
  82236. æFc SysEqu.h
  82237. æT #define
  82238. æD #define CrsrPin 0x834 /*[GLOBAL VAR]  cursor pinning rectangle [8 bytes]*/
  82239. æC 
  82240.  
  82241. æKY CrsrCouple
  82242. æFc SysEqu.h
  82243. æT #define
  82244. æD #define CrsrCouple 0x8CF /*[GLOBAL VAR]  cursor coupled to mouse? [byte]*/
  82245. æC 
  82246.  
  82247. æKY CrsrScale
  82248. æFc SysEqu.h
  82249. æT #define
  82250. æD #define CrsrScale 0x8D3 /*[GLOBAL VAR]  cursor scaled? [byte]*/
  82251. æC 
  82252.  
  82253. æKY MouseMask
  82254. æFc SysEqu.h
  82255. æT #define
  82256. æD #define MouseMask 0x8D6 /*[GLOBAL VAR]  V-H mask for ANDing with mouse [long]*/
  82257. æC 
  82258.  
  82259. æKY MouseOffset
  82260. æFc SysEqu.h
  82261. æT #define
  82262. æD #define MouseOffset 0x8DA /*[GLOBAL VAR]  V-H offset for adding after ANDing [long]*/
  82263. æC 
  82264.  
  82265. æKY AlarmState
  82266. æFc SysEqu.h
  82267. æT #define
  82268. æD #define AlarmState 0x21F /*[GLOBAL VAR]  Bit7=parity, Bit6=beeped, Bit0=enable [byte]*/
  82269. æC 
  82270.  
  82271. æKY VBLQueue
  82272. æFc SysEqu.h
  82273. æT #define
  82274. æD #define VBLQueue 0x160 /*[GLOBAL VAR] Vertical retrace queue header (10 bytes)
  82275.    VBL queue header [10 bytes]*/
  82276. æC 
  82277.  
  82278. æKY SysEvtMask
  82279. æFc SysEqu.h
  82280. æT #define
  82281. æD #define SysEvtMask 0x144 /*[GLOBAL VAR] System event mask (word)
  82282.    system event mask [word]*/
  82283. æC 
  82284.  
  82285. æKY SysEvtBuf
  82286. æFc SysEqu.h
  82287. æT #define
  82288. æD #define SysEvtBuf 0x146 /*[GLOBAL VAR]  system event queue element buffer [pointer]*/
  82289. æC 
  82290.  
  82291. æKY EventQueue
  82292. æFc SysEqu.h
  82293. æT #define
  82294. æD #define EventQueue 0x14A /*[GLOBAL VAR] Event queue header (10 bytes)
  82295.    event queue header [10 bytes]*/
  82296. æC 
  82297.  
  82298. æKY EvtBufCnt
  82299. æFc SysEqu.h
  82300. æT #define
  82301. æD #define EvtBufCnt 0x154 /*[GLOBAL VAR]  max number of events in SysEvtBuf - 1 [word]*/
  82302. æC 
  82303.  
  82304. æKY GZRootHnd
  82305. æFc SysEqu.h
  82306. æT #define
  82307. æD #define GZRootHnd 0x328 /*[GLOBAL VAR] Handle to relocatable block not to be moved by grow zone function
  82308.    root handle for GrowZone [handle]*/
  82309. æC 
  82310.  
  82311. æKY GZRootPtr
  82312. æFc SysEqu.h
  82313. æT #define
  82314. æD #define GZRootPtr 0x32C /*[GLOBAL VAR]  root pointer for GrowZone [pointer]*/
  82315. æC 
  82316.  
  82317. æKY GZMoveHnd
  82318. æFc SysEqu.h
  82319. æT #define
  82320. æD #define GZMoveHnd 0x330 /*[GLOBAL VAR]  moving handle for GrowZone [handle]*/
  82321. æC 
  82322.  
  82323. æKY MemTop
  82324. æFc SysEqu.h
  82325. æT #define
  82326. æD #define MemTop 0x108 /*[GLOBAL VAR] Address of end of RAM (on Macintosh XL, end of RAM available to applications)
  82327.    top of memory [pointer]*/
  82328. æC 
  82329.  
  82330. æKY MmInOK
  82331. æFc SysEqu.h
  82332. æT #define
  82333. æD #define MmInOK 0x12E /*[GLOBAL VAR]  initial memory mgr checks ok? [byte]*/
  82334. æC 
  82335.  
  82336. æKY HpChk
  82337. æFc SysEqu.h
  82338. æT #define
  82339. æD #define HpChk 0x316 /*[GLOBAL VAR]  heap check RAM code [pointer]*/
  82340. æC 
  82341.  
  82342. æKY MaskBC
  82343. æFc SysEqu.h
  82344. æT #define
  82345. æD #define MaskBC 0x31A /*[GLOBAL VAR]  Memory Manager Byte Count Mask [long]*/
  82346. æC 
  82347.  
  82348. æKY MaskHandle
  82349. æFc SysEqu.h
  82350. æT #define
  82351. æD #define MaskHandle 0x31A /*[GLOBAL VAR]  Memory Manager Handle Mask [long]*/
  82352. æC 
  82353.  
  82354. æKY MaskPtr
  82355. æFc SysEqu.h
  82356. æT #define
  82357. æD #define MaskPtr 0x31A /*[GLOBAL VAR]  Memory Manager Pointer Mask [long]*/
  82358. æC 
  82359.  
  82360. æKY MinStack
  82361. æFc SysEqu.h
  82362. æT #define
  82363. æD #define MinStack 0x31E /*[GLOBAL VAR] Minimum space allotment for stack (long)
  82364.    min stack size used in InitApplZone [long]*/
  82365. æC 
  82366.  
  82367. æKY DefltStack
  82368. æFc SysEqu.h
  82369. æT #define
  82370. æD #define DefltStack 0x322 /*[GLOBAL VAR] Default space allotment for stack (long) 
  82371.    default size of stack [long]*/
  82372. æC 
  82373.  
  82374. æKY MMDefFlags
  82375. æFc SysEqu.h
  82376. æT #define
  82377. æD #define MMDefFlags 0x326 /*[GLOBAL VAR]  default zone flags [word]*/
  82378. æC 
  82379.  
  82380. æKY DSAlertTab
  82381. æFc SysEqu.h
  82382. æT #define
  82383. æD #define DSAlertTab 0x2BA /*[GLOBAL VAR] Pointer to system error alert table in use
  82384.    system error alerts [pointer]*/
  82385. æC 
  82386.  
  82387. æKY DSAlertRect
  82388. æFc SysEqu.h
  82389. æT #define
  82390. æD #define DSAlertRect 0x3F8 /*[GLOBAL VAR] Rectangle enclosing system error alert (8 bytes)
  82391.    rectangle for disk-switch alert [8 bytes]*/
  82392. æC 
  82393.  
  82394. æKY DSDrawProc
  82395. æFc SysEqu.h
  82396. æT #define
  82397. æD #define DSDrawProc 0x334 /*[GLOBAL VAR]  alternate syserror draw procedure [pointer]*/
  82398. æC 
  82399.  
  82400. æKY DSWndUpdate
  82401. æFc SysEqu.h
  82402. æT #define
  82403. æD #define DSWndUpdate 0x15D /*[GLOBAL VAR]  GNE not to paintBehind DS AlertRect? [byte]*/
  82404. æC 
  82405.  
  82406. æKY WWExist
  82407. æFc SysEqu.h
  82408. æT #define
  82409. æD #define WWExist 0x8F2 /*[GLOBAL VAR]  window manager initialized? [byte]*/
  82410. æC 
  82411.  
  82412. æKY QDExist
  82413. æFc SysEqu.h
  82414. æT #define
  82415. æD #define QDExist 0x8F3 /*[GLOBAL VAR]  quickdraw is initialized [byte]*/
  82416. æC 
  82417.  
  82418. æKY ResumeProc
  82419. æFc SysEqu.h
  82420. æT #define
  82421. æD #define ResumeProc 0xA8C /*[GLOBAL VAR] Address of resume procedure
  82422.    Resume procedure from InitDialogs [pointer]*/
  82423. æC 
  82424.  
  82425. æKY DSErrCode
  82426. æFc SysEqu.h
  82427. æT #define
  82428. æD #define DSErrCode 0xAF0 /*[GLOBAL VAR] Current system error ID (word)
  82429.    last system error alert ID*/
  82430. æC 
  82431.  
  82432. æKY IntFlag
  82433. æFc SysEqu.h
  82434. æT #define
  82435. æD #define IntFlag 0x15F /*[GLOBAL VAR]  reduce interrupt disable time when bit 7 = 0*/
  82436. æC 
  82437.  
  82438. æKY SerialVars
  82439. æFc SysEqu.h
  82440. æT #define
  82441. æD #define SerialVars 0x2D0 /*[GLOBAL VAR]  async driver variables [16 bytes]*/
  82442. æC 
  82443.  
  82444. æKY ABusVars
  82445. æFc SysEqu.h
  82446. æT #define
  82447. æD #define ABusVars 0x2D8 /*[GLOBAL VAR] Pointer to AppleTalk variables
  82448.   ;Pointer to AppleTalk local variables*/
  82449. æC 
  82450.  
  82451. æKY ABusDCE
  82452. æFc SysEqu.h
  82453. æT #define
  82454. æD #define ABusDCE 0x2DC /*[GLOBAL VAR] ;Pointer to AppleTalk DCE*/
  82455. æC 
  82456.  
  82457. æKY PortAUse
  82458. æFc SysEqu.h
  82459. æT #define
  82460. æD #define PortAUse 0x290 /*[GLOBAL VAR]  bit 7: 1 = not in use, 0 = in use*/
  82461. æC 
  82462.  
  82463. æKY PortBUse
  82464. æFc SysEqu.h
  82465. æT #define
  82466. æD #define PortBUse 0x291 /*[GLOBAL VAR] Current availability of serial port B (byte)
  82467.    port B use, same format as PortAUse*/
  82468. æC 
  82469.  
  82470. æKY SCCASts
  82471. æFc SysEqu.h
  82472. æT #define
  82473. æD #define SCCASts 0x2CE /*[GLOBAL VAR]  SCC read reg 0 last ext/sts rupt - A [byte]*/
  82474. æC 
  82475.  
  82476. æKY SCCBSts
  82477. æFc SysEqu.h
  82478. æT #define
  82479. æD #define SCCBSts 0x2CF /*[GLOBAL VAR]  SCC read reg 0 last ext/sts rupt - B [byte]*/
  82480. æC 
  82481.  
  82482. æKY DskErr
  82483. æFc SysEqu.h
  82484. æT #define
  82485. æD #define DskErr 0x142 /*[GLOBAL VAR]  disk routine result code [word]*/
  82486. æC 
  82487.  
  82488. æKY PWMBuf2
  82489. æFc SysEqu.h
  82490. æT #define
  82491. æD #define PWMBuf2 0x312 /*[GLOBAL VAR]  PWM buffer 1 (or 2 if sound) [pointer]*/
  82492. æC 
  82493.  
  82494. æKY SoundPtr
  82495. æFc SysEqu.h
  82496. æT #define
  82497. æD #define SoundPtr 0x262 /*[GLOBAL VAR] Pointer to four-tone record
  82498.    4VE sound definition table [pointer]*/
  82499. æC 
  82500.  
  82501. æKY SoundBase
  82502. æFc SysEqu.h
  82503. æT #define
  82504. æD #define SoundBase 0x266 /*[GLOBAL VAR] Pointer to free-form synthesizer buffer
  82505.    sound bitMap [pointer]*/
  82506. æC 
  82507.  
  82508. æKY SoundVBL
  82509. æFc SysEqu.h
  82510. æT #define
  82511. æD #define SoundVBL 0x26A /*[GLOBAL VAR]  vertical retrace control element [16 bytes]*/
  82512. æC 
  82513.  
  82514. æKY SoundDCE
  82515. æFc SysEqu.h
  82516. æT #define
  82517. æD #define SoundDCE 0x27A /*[GLOBAL VAR]  sound driver DCE [pointer]*/
  82518. æC 
  82519.  
  82520. æKY SoundActive
  82521. æFc SysEqu.h
  82522. æT #define
  82523. æD #define SoundActive 0x27E /*[GLOBAL VAR]  sound is active? [byte]*/
  82524. æC 
  82525.  
  82526. æKY SoundLevel
  82527. æFc SysEqu.h
  82528. æT #define
  82529. æD #define SoundLevel 0x27F /*[GLOBAL VAR] Amplitude in 740-byte buffer (byte)
  82530.    current level in buffer [byte]*/
  82531. æC 
  82532.  
  82533. æKY CurPitch
  82534. æFc SysEqu.h
  82535. æT #define
  82536. æD #define CurPitch 0x280 /*[GLOBAL VAR] Value of count in square-wave synthesizer buffer (word)
  82537.    current pitch value [word]*/
  82538. æC 
  82539.  
  82540. æKY DskVerify
  82541. æFc SysEqu.h
  82542. æT #define
  82543. æD #define DskVerify 0x12C /*[GLOBAL VAR]  used by 3.5 disk driver for read/verify [byte]*/
  82544. æC 
  82545.  
  82546. æKY TagData
  82547. æFc SysEqu.h
  82548. æT #define
  82549. æD #define TagData 0x2FA /*[GLOBAL VAR]  sector tag info for disk drivers [14 bytes]*/
  82550. æC 
  82551.  
  82552. æKY BufTgFNum
  82553. æFc SysEqu.h
  82554. æT #define
  82555. æD #define BufTgFNum 0x2FC /*[GLOBAL VAR] File tags buffer:  file number (long)
  82556.    file number [long]*/
  82557. æC 
  82558.  
  82559. æKY BufTgFFlg
  82560. æFc SysEqu.h
  82561. æT #define
  82562. æD #define BufTgFFlg 0x300 /*[GLOBAL VAR] File tags buffer:  flags (word:  bit 1=1 if resource fork) 
  82563.    flags [word]*/
  82564. æC 
  82565.  
  82566. æKY BufTgFBkNum
  82567. æFc SysEqu.h
  82568. æT #define
  82569. æD #define BufTgFBkNum 0x302 /*[GLOBAL VAR] File tags buffer:  logical block number (word)
  82570.    logical block number [word]*/
  82571. æC 
  82572.  
  82573. æKY BufTgDate
  82574. æFc SysEqu.h
  82575. æT #define
  82576. æD #define BufTgDate 0x304 /*[GLOBAL VAR] File tags buffer:  date and time of last modification (long)
  82577.    time stamp [word]*/
  82578. æC 
  82579.  
  82580. æKY ScrDmpEnb
  82581. æFc SysEqu.h
  82582. æT #define
  82583. æD #define ScrDmpEnb 0x2F8 /*[GLOBAL VAR] 0 if GetNextEvent shouldn't process Command-Shift-number combinations (byte)
  82584.    screen dump enabled? [byte]*/
  82585. æC 
  82586.  
  82587. æKY ScrDmpType
  82588. æFc SysEqu.h
  82589. æT #define
  82590. æD #define ScrDmpType 0x2F9 /*[GLOBAL VAR]  FF dumps screen, FE dumps front window [byte]*/
  82591. æC 
  82592.  
  82593. æKY ScrapVars
  82594. æFc SysEqu.h
  82595. æT #define
  82596. æD #define ScrapVars 0x960 /*[GLOBAL VAR]  scrap manager variables [32 bytes]*/
  82597. æC 
  82598.  
  82599. æKY ScrapInfo
  82600. æFc SysEqu.h
  82601. æT #define
  82602. æD #define ScrapInfo 0x960 /*[GLOBAL VAR]  scrap length [long]*/
  82603. æC 
  82604.  
  82605. æKY ScrapEnd
  82606. æFc SysEqu.h
  82607. æT #define
  82608. æD #define ScrapEnd 0x980 /*[GLOBAL VAR]  end of scrap vars*/
  82609. æC 
  82610.  
  82611. æKY ScrapTag
  82612. æFc SysEqu.h
  82613. æT #define
  82614. æD #define ScrapTag 0x970 /*[GLOBAL VAR]  scrap file name [STRING[15]]*/
  82615. æC 
  82616.  
  82617. æKY LaunchFlag
  82618. æFc SysEqu.h
  82619. æT #define
  82620. æD #define LaunchFlag 0x902 /*[GLOBAL VAR]  from launch or chain [byte]*/
  82621. æC 
  82622.  
  82623. æKY SaveSegHandle
  82624. æFc SysEqu.h
  82625. æT #define
  82626. æD #define SaveSegHandle 0x930 /*[GLOBAL VAR]  seg 0 handle [handle]*/
  82627. æC 
  82628.  
  82629. æKY CurJTOffset
  82630. æFc SysEqu.h
  82631. æT #define
  82632. æD #define CurJTOffset 0x934 /*[GLOBAL VAR] Offset to jump table from location pointed to by A5 (word)
  82633.    current jump table offset [word]*/
  82634. æC 
  82635.  
  82636. æKY CurPageOption
  82637. æFc SysEqu.h
  82638. æT #define
  82639. æD #define CurPageOption 0x936 /*[GLOBAL VAR] Sound/screen buffer configuration passed to Chain or Launch (word)
  82640.    current page 2 configuration [word]*/
  82641. æC 
  82642.  
  82643. æKY LoaderPBlock
  82644. æFc SysEqu.h
  82645. æT #define
  82646. æD #define LoaderPBlock 0x93A /*[GLOBAL VAR]  param block for ExitToShell [10 bytes]*/
  82647. æC 
  82648.  
  82649. æKY CurApRefNum
  82650. æFc SysEqu.h
  82651. æT #define
  82652. æD #define CurApRefNum 0x900 /*[GLOBAL VAR] Reference number of current application's resource file (word)
  82653.    refNum of application's resFile [word]*/
  82654. æC 
  82655.  
  82656. æKY CurrentA5
  82657. æFc SysEqu.h
  82658. æT #define
  82659. æD #define CurrentA5 0x904 /*[GLOBAL VAR] Address of boundary between application globals and application parameters
  82660.    current value of A5 [pointer]*/
  82661. æC 
  82662.  
  82663. æKY CurStackBase
  82664. æFc SysEqu.h
  82665. æT #define
  82666. æD #define CurStackBase 0x908 /*[GLOBAL VAR] Address of base of stack; start of application globals
  82667.    current stack base [pointer]*/
  82668. æC 
  82669.  
  82670. æKY CurApName
  82671. æFc SysEqu.h
  82672. æT #define
  82673. æD #define CurApName 0x910 /*[GLOBAL VAR] Name of current application (length byte followed by up to 31 characters)
  82674.    name of application [STRING[31]]*/
  82675. æC 
  82676.  
  82677. æKY LoadTrap
  82678. æFc SysEqu.h
  82679. æT #define
  82680. æD #define LoadTrap 0x12D /*[GLOBAL VAR]  trap before launch? [byte]*/
  82681. æC 
  82682.  
  82683. æKY SegHiEnable
  82684. æFc SysEqu.h
  82685. æT #define
  82686. æD #define SegHiEnable 0xBB2 /*[GLOBAL VAR]  (byte) 0 to disable MoveHHi in LoadSeg*/
  82687. æC 
  82688.  
  82689. æKY WindowList
  82690. æFc SysEqu.h
  82691. æT #define
  82692. æD 
  82693. /* Window Manager Globals */
  82694.  
  82695. #define WindowList 0x9D6 /*[GLOBAL VAR] Pointer to first window in window list; 0 if using events but not windows
  82696.   Z-ordered linked list of windows [pointer]*/
  82697. æC 
  82698.  
  82699. æKY PaintWhite
  82700. æFc SysEqu.h
  82701. æT #define
  82702. æD #define PaintWhite 0x9DC /*[GLOBAL VAR] Flag for whether to paint window white before update event (word)
  82703.   erase newly drawn windows? [word]*/
  82704. æC 
  82705.  
  82706. æKY WMgrPort
  82707. æFc SysEqu.h
  82708. æT #define
  82709. æD #define WMgrPort 0x9DE /*[GLOBAL VAR] Pointer to Window Manager port 
  82710.   window manager's grafport [pointer]*/
  82711. æC 
  82712.  
  82713. æKY GrayRgn
  82714. æFc SysEqu.h
  82715. æT #define
  82716. æD #define GrayRgn 0x9EE /*[GLOBAL VAR] Handle to region drawn as desktop
  82717.   rounded gray desk region [handle]*/
  82718. æC 
  82719.  
  82720. æKY CurActivate
  82721. æFc SysEqu.h
  82722. æT #define
  82723. æD #define CurActivate 0xA64 /*[GLOBAL VAR] Pointer to window to receive activate event
  82724.   window slated for activate event [pointer]*/
  82725. æC 
  82726.  
  82727. æKY CurDeactive
  82728. æFc SysEqu.h
  82729. æT #define
  82730. æD #define CurDeactive 0xA68 /*[GLOBAL VAR] Pointer to window to receive deactivate event
  82731.   window slated for deactivate event [pointer]*/
  82732. æC 
  82733.  
  82734. æKY DragHook
  82735. æFc SysEqu.h
  82736. æT #define
  82737. æD #define DragHook 0x9F6 /*[GLOBAL VAR] Address of procedure to execute during TrackGoAway, DragWindow, GrowWindow, DragGrayRgn, TrackControl, and DragControl
  82738.   user hook during dragging [pointer]*/
  82739. æC 
  82740.  
  82741. æKY DeskPattern
  82742. æFc SysEqu.h
  82743. æT #define
  82744. æD #define DeskPattern 0xA3C /*[GLOBAL VAR] Pattern with which desktop is painted (8 bytes)
  82745.   desk pattern [8 bytes]*/
  82746. æC 
  82747.  
  82748. æKY DeskHook
  82749. æFc SysEqu.h
  82750. æT #define
  82751. æD #define DeskHook 0xA6C /*[GLOBAL VAR] Address of procedure for painting desktop or responding to clicks on desktop
  82752.   hook for painting the desk [pointer]*/
  82753. æC 
  82754.  
  82755. æKY GhostWindow
  82756. æFc SysEqu.h
  82757. æT #define
  82758. æD #define GhostWindow 0xA84 /*[GLOBAL VAR] Pointer to window never to be considered frontmost
  82759.   window hidden from FrontWindow [pointer]*/
  82760. æC 
  82761.  
  82762. æKY TEDoText
  82763. æFc SysEqu.h
  82764. æT #define
  82765. æD 
  82766. /* Text Edit Globals */
  82767.  
  82768. #define TEDoText 0xA70 /*[GLOBAL VAR] Address of TextEdit multi-purpose routine
  82769.   textEdit doText proc hook [pointer]*/
  82770. æC 
  82771. __________________________________________________________________________________
  82772.  
  82773. Assembly-language note:  The global variable TEDoText contains the address of 
  82774. a multi-purpose text editing routine that advanced programmers may find useful.  
  82775. It lets you display, highlight, and hit-test characters, and position the pen to 
  82776. draw the caret.  "Hit-test" means decide where to place the insertion point when 
  82777. the user clicks the mouse button; the point selected with the mouse is in the 
  82778. teSelPoint field.  The registers contain the following:
  82779.  
  82780. On entry           A3:         pointer to the locked edit  record
  82781.                    D3:         position of first character to be redrawn  (word)
  82782.                    D4:         position of last character to be redrawn  (word)
  82783.                    D7:         (word)     0 to hit-test a character 
  82784.                                               1 to highlight the selection range
  82785.                                               –1 to display the text 
  82786.                                               –2 to position the pen to draw the caret
  82787.  
  82788. On exit            A0:         pointer to current grafPort 
  82789.                    D0:         if hit-testing, character position or –1 for none (word) 
  82790. __________________________________________________________________________________
  82791.  
  82792. æKY TERecal
  82793. æFc SysEqu.h
  82794. æT #define
  82795. æD #define TERecal 0xA74 /*[GLOBAL VAR] Address of routine to recalculate line starts for TextEdit
  82796.   textEdit recalText proc hook [pointer]*/
  82797. æC 
  82798.  
  82799. æKY TEScrpLength
  82800. æFc SysEqu.h
  82801. æT #define
  82802. æD #define TEScrpLength 0xAB0 /*[GLOBAL VAR] Size in bytes of TextEdit scrap (long)
  82803.   textEdit Scrap Length [word]*/
  82804. æC 
  82805.  
  82806. æKY TEScrpHandle
  82807. æFc SysEqu.h
  82808. æT #define
  82809. æD #define TEScrpHandle 0xAB4 /*[GLOBAL VAR] Handle to TextEdit scrap
  82810.   textEdit Scrap [handle]*/
  82811. æC 
  82812.  
  82813. æKY TEWdBreak
  82814. æFc SysEqu.h
  82815. æT #define
  82816. æD #define TEWdBreak 0xAF6 /*[GLOBAL VAR] default word break routine [pointer]*/
  82817. æC 
  82818.  
  82819. æKY WordRedraw
  82820. æFc SysEqu.h
  82821. æT #define
  82822. æD #define WordRedraw 0xBA5 /*[GLOBAL VAR] (byte) - used by TextEdit RecalDraw*/
  82823. æC 
  82824.  
  82825. æKY TESysJust
  82826. æFc SysEqu.h
  82827. æT #define
  82828. æD #define TESysJust 0xBAC /*[GLOBAL VAR] (word) system justification (intl. textEdit)*/
  82829. æC 
  82830.  
  82831. æKY TopMapHndl
  82832. æFc SysEqu.h
  82833. æT #define
  82834. æD 
  82835. /* Resource Manager Globals */
  82836.  
  82837. #define TopMapHndl 0xA50 /*[GLOBAL VAR] Handle to resource map of most recently opened resource file
  82838.   topmost map in list [handle]*/
  82839. æC 
  82840.  
  82841. æKY SysMapHndl
  82842. æFc SysEqu.h
  82843. æT #define
  82844. æD #define SysMapHndl 0xA54 /*[GLOBAL VAR] Handle to map of system resource file
  82845.   system map [handle]*/
  82846. æC 
  82847.  
  82848. æKY SysMap
  82849. æFc SysEqu.h
  82850. æT #define
  82851. æD #define SysMap 0xA58 /*[GLOBAL VAR] Reference number of system resource file (word)
  82852.   reference number of system map [word]*/
  82853. æC 
  82854.  
  82855. æKY CurMap
  82856. æFc SysEqu.h
  82857. æT #define
  82858. æD #define CurMap 0xA5A /*[GLOBAL VAR] Reference number of current resource file (word) 
  82859.   reference number of current map [word]*/
  82860. æC 
  82861.  
  82862. æKY ResReadOnly
  82863. æFc SysEqu.h
  82864. æT #define
  82865. æD #define ResReadOnly 0xA5C /*[GLOBAL VAR] Read only flag [word]*/
  82866. æC 
  82867.  
  82868. æKY ResLoad
  82869. æFc SysEqu.h
  82870. æT #define
  82871. æD #define ResLoad 0xA5E /*[GLOBAL VAR] Current SetResLoad state (word)
  82872.   Auto-load feature [word]*/
  82873. æC 
  82874.  
  82875. æKY ResErr
  82876. æFc SysEqu.h
  82877. æT #define
  82878. æD #define ResErr 0xA60 /*[GLOBAL VAR] Current value of ResError (word)
  82879.   Resource error code [word]*/
  82880. æC 
  82881.  
  82882. æKY ResErrProc
  82883. æFc SysEqu.h
  82884. æT #define
  82885. æD #define ResErrProc 0xAF2 /*[GLOBAL VAR] Address of resource error procedure
  82886.   Resource error procedure [pointer]*/
  82887. æC 
  82888.  
  82889. æKY SysResName
  82890. æFc SysEqu.h
  82891. æT #define
  82892. æD #define SysResName 0xAD8 /*[GLOBAL VAR] Name of system resource file (length byte followed by up to 19 characters)
  82893.   Name of system resource file [STRING[19]]*/
  82894. æC 
  82895.  
  82896. æKY RomMapInsert
  82897. æFc SysEqu.h
  82898. æT #define
  82899. æD #define RomMapInsert 0xB9E /*[GLOBAL VAR] (byte) determines if we should link in map*/
  82900. æC 
  82901.  
  82902. æKY TmpResLoad
  82903. æFc SysEqu.h
  82904. æT #define
  82905. æD #define TmpResLoad 0xB9F /*[GLOBAL VAR] second byte is temporary ResLoad value.*/
  82906. æC 
  82907.  
  82908. æKY MBarHeight
  82909. æFc SysEqu.h
  82910. æT #define
  82911. æD 
  82912. /* Menu Mgr globals */
  82913.  
  82914. #define MBarHeight 0xBAA /*[GLOBAL VAR] height of the menu bar*/
  82915. æC 
  82916.  
  82917. æKY CommToolboxGlobals
  82918. æFc SysEqu.h
  82919. æT #define
  82920. æD 
  82921. /* CommToolbox Global */
  82922.  
  82923. #define CommToolboxGlobals 0x0BB4 /*[GLOBAL VAR] pointer to CommToolbox globals */
  82924. æC 
  82925.  
  82926.  
  82927. æKY TextEdit.h
  82928. æKL GetStylHandle
  82929. GetStylScrap
  82930. SetClikLoop
  82931. SetStylHandle
  82932. SetStylScrap
  82933. SetWordBreak
  82934. TEActivate
  82935. TEAutoView
  82936. TECalText
  82937. teclick
  82938. TEClick
  82939. TEContinuousStyle
  82940. TECopy
  82941. TECustomHook
  82942. TECut
  82943. TEDeactivate
  82944. TEDelete
  82945. TEDispose
  82946. TEFeatureFlag
  82947. TEFromScrap
  82948. TEGetHeight
  82949. TEGetOffset
  82950. TEGetPoint
  82951. TEGetScrapLen
  82952. TEGetStyle
  82953. TEGetText
  82954. TEIdle
  82955. TEInit
  82956. TEInsert
  82957. TEKey
  82958. TENew
  82959. TENumStyles
  82960. TEPaste
  82961. TEPinScroll
  82962. TEReplaceStyle
  82963. TEScrapHandle
  82964. TEScroll
  82965. TESelView
  82966. TESetJust
  82967. TESetScrapLen
  82968. TESetSelect
  82969. TESetStyle
  82970. TESetText
  82971. TEStylInsert
  82972. TEStylNew
  82973. TEStylPaste
  82974. TEToScrap
  82975. TEUpdate
  82976. TextBox
  82977.  
  82978. addSize
  82979. addSizeBit
  82980. Chars
  82981. ClikLoopProcPtr
  82982. clrBit
  82983. doAll
  82984. doColor
  82985. doFace
  82986. doFont
  82987. doSize
  82988. doToggle
  82989. DRAWHook
  82990. EOLHook
  82991. faceBit
  82992. fontBit
  82993. HITTESTHook
  82994. intDrawHook
  82995. intEOLHook
  82996. intHitTestHook
  82997. intNWidthHook
  82998. intWidthHook
  82999. LHElement
  83000. NullStHandle
  83001. NullStPtr
  83002. NullStRec
  83003. nWIDTHHook
  83004. ScrpSTElement
  83005. sizeBit
  83006. STElement
  83007. StScrpHandle
  83008. StScrpPtr
  83009. StScrpRec
  83010. StyleRun
  83011. TEBitClear
  83012. TEBitSet
  83013. TEBitTest
  83014. teCenter
  83015. teFAutoScr
  83016. teFlushDefault
  83017. teFlushLeft
  83018. teFlushRight
  83019. teForceLeft
  83020. teFOutlineHilite
  83021. teFromFind
  83022. teFromRecal
  83023. teFTextBuffering
  83024. TEHandle
  83025. TEIntHook
  83026. teJustCenter
  83027. teJustLeft
  83028. teJustRight
  83029. TEPtr
  83030. TERec
  83031. TEStyleHandle
  83032. TEStylePtr
  83033. TEStyleRec
  83034. teWordDrag
  83035. teWordSelect
  83036. TextStyle
  83037. TextStyleHandle
  83038. TextStylePtr
  83039. toglBit
  83040. WIDTHHook
  83041. WordBreakProcPtr
  83042.  
  83043. æKY teJustLeft
  83044. æFc TextEdit.h
  83045. æT #define
  83046. æD 
  83047. /* Justification styles */
  83048.  
  83049. #define teJustLeft 0
  83050. æC 
  83051.  
  83052. æKY teJustCenter
  83053. æFc TextEdit.h
  83054. æT #define
  83055. æD #define teJustCenter 1
  83056. æC 
  83057.  
  83058. æKY teJustRight
  83059. æFc TextEdit.h
  83060. æT #define
  83061. æD #define teJustRight -1
  83062. æC 
  83063.  
  83064. æKY teForceLeft
  83065. æFc TextEdit.h
  83066. æT #define
  83067. æD #define teForceLeft -2
  83068. æC 
  83069.  
  83070. æKY teFlushDefault
  83071. æFc TextEdit.h
  83072. æT #define
  83073. æD 
  83074. /* new names for the Justification styles  */
  83075.  
  83076. #define teFlushDefault 0 /*flush according to the line direction */
  83077. æC 
  83078.  
  83079. æKY teCenter
  83080. æFc TextEdit.h
  83081. æT #define
  83082. æD #define teCenter 1 /*center justify */
  83083. æC 
  83084.  
  83085. æKY teFlushRight
  83086. æFc TextEdit.h
  83087. æT #define
  83088. æD #define teFlushRight -1 /*flush right for all scripts */
  83089. æC 
  83090.  
  83091. æKY teFlushLeft
  83092. æFc TextEdit.h
  83093. æT #define
  83094. æD #define teFlushLeft -2 /*flush left for all scripts */
  83095. æC 
  83096.  
  83097. æKY fontBit
  83098. æFc TextEdit.h
  83099. æT #define
  83100. æD 
  83101. /* Set/Replace style modes */
  83102.  
  83103. #define fontBit 0 /*set font*/
  83104. æC 
  83105.  
  83106. æKY faceBit
  83107. æFc TextEdit.h
  83108. æT #define
  83109. æD #define faceBit 1 /*set face*/
  83110. æC 
  83111.  
  83112. æKY sizeBit
  83113. æFc TextEdit.h
  83114. æT #define
  83115. æD #define sizeBit 2 /*set size*/
  83116. æC 
  83117.  
  83118. æKY clrBit
  83119. æFc TextEdit.h
  83120. æT #define
  83121. æD #define clrBit 3 /*set color*/
  83122. æC 
  83123.  
  83124. æKY addSizeBit
  83125. æFc TextEdit.h
  83126. æT #define
  83127. æD #define addSizeBit 4 /*add size mode*/
  83128. æC 
  83129.  
  83130. æKY toglBit
  83131. æFc TextEdit.h
  83132. æT #define
  83133. æD #define toglBit 5 /*set faces in toggle mode*/
  83134. æC 
  83135.  
  83136. æKY doFont
  83137. æFc TextEdit.h
  83138. æT #define
  83139. æD #define doFont 1 /* set font (family) number*/
  83140. æC 
  83141.  
  83142. æKY doFace
  83143. æFc TextEdit.h
  83144. æT #define
  83145. æD #define doFace 2 /*set character style*/
  83146. æC 
  83147.  
  83148. æKY doSize
  83149. æFc TextEdit.h
  83150. æT #define
  83151. æD #define doSize 4 /*set type size*/
  83152. æC 
  83153.  
  83154. æKY doColor
  83155. æFc TextEdit.h
  83156. æT #define
  83157. æD #define doColor 8 /*set color*/
  83158. æC 
  83159.  
  83160. æKY doAll
  83161. æFc TextEdit.h
  83162. æT #define
  83163. æD #define doAll 15 /*set all attributes*/
  83164. æC 
  83165.  
  83166. æKY addSize
  83167. æFc TextEdit.h
  83168. æT #define
  83169. æD #define addSize 16 /*adjust type size*/
  83170. æC 
  83171.  
  83172. æKY doToggle
  83173. æFc TextEdit.h
  83174. æT #define
  83175. æD #define doToggle 32 /*toggle mode for TESetStyle & TEContinuousStyle*/
  83176. æC 
  83177.  
  83178. æKY EOLHook
  83179. æFc TextEdit.h
  83180. æT #define
  83181. æD 
  83182. /* offsets into TEDispatchRec */
  83183.  
  83184. #define EOLHook 0 /*[ProcPtr] TEEOLHook*/
  83185. æC 
  83186.  
  83187. æKY DRAWHook
  83188. æFc TextEdit.h
  83189. æT #define
  83190. æD #define DRAWHook 4 /*[ProcPtr] TEWidthHook*/
  83191. æC 
  83192.  
  83193. æKY WIDTHHook
  83194. æFc TextEdit.h
  83195. æT #define
  83196. æD #define WIDTHHook 8 /*[ProcPtr] TEDrawHook*/
  83197. æC 
  83198.  
  83199. æKY HITTESTHook
  83200. æFc TextEdit.h
  83201. æT #define
  83202. æD #define HITTESTHook 12 /*[ProcPtr] TEHitTestHook*/
  83203. æC 
  83204.  
  83205. æKY nWIDTHHook
  83206. æFc TextEdit.h
  83207. æT #define
  83208. æD #define nWIDTHHook 24 /*[ProcPtr] nTEWidthHook <6>*/
  83209. æC 
  83210.  
  83211. æKY intEOLHook
  83212. æFc TextEdit.h
  83213. æT #define
  83214. æD 
  83215. /* selectors for TECustomHook */
  83216.  
  83217. #define intEOLHook 0 /*TEIntHook value*/
  83218. æC 
  83219.  
  83220. æKY intDrawHook
  83221. æFc TextEdit.h
  83222. æT #define
  83223. æD #define intDrawHook 1 /*TEIntHook value*/
  83224. æC 
  83225.  
  83226. æKY intWidthHook
  83227. æFc TextEdit.h
  83228. æT #define
  83229. æD #define intWidthHook 2 /*TEIntHook value*/
  83230. æC 
  83231.  
  83232. æKY intHitTestHook
  83233. æFc TextEdit.h
  83234. æT #define
  83235. æD #define intHitTestHook 3 /*TEIntHook value*/
  83236. æC 
  83237.  
  83238. æKY intNWidthHook
  83239. æFc TextEdit.h
  83240. æT #define
  83241. æD #define intNWidthHook 6 /*new TEIntHook value for new version of WidthHook <6>*/
  83242. æC 
  83243.  
  83244. æKY teFAutoScr
  83245. æFc TextEdit.h
  83246. æT #define
  83247. æD 
  83248. /* feature or bit definitions for newTEFlags */
  83249.  
  83250. #define teFAutoScr 0 /*00000000b*/
  83251. æC 
  83252.  
  83253. æKY teFTextBuffering
  83254. æFc TextEdit.h
  83255. æT #define
  83256. æD #define teFTextBuffering 1 /*00000010b*/
  83257. æC 
  83258.  
  83259. æKY teFOutlineHilite
  83260. æFc TextEdit.h
  83261. æT #define
  83262. æD #define teFOutlineHilite 2 /*00000100b*/
  83263. æC 
  83264.  
  83265. æKY TEBitClear
  83266. æFc TextEdit.h
  83267. æT #define
  83268. æD 
  83269. /* action for the new "bit (un)set" interface, TEFeatureFlag */
  83270.  
  83271. #define TEBitClear 0
  83272. æC 
  83273.  
  83274. æKY TEBitSet
  83275. æFc TextEdit.h
  83276. æT #define
  83277. æD #define TEBitSet 1 /*set the selector bit*/
  83278. æC 
  83279.  
  83280. æKY TEBitTest
  83281. æFc TextEdit.h
  83282. æT #define
  83283. æD #define TEBitTest -1 /*no change; just return the current setting*/
  83284. æC 
  83285.  
  83286. æKY teWordSelect
  83287. æFc TextEdit.h
  83288. æT #define
  83289. æD 
  83290. /* constants for identifying the routine that called FindWord  */
  83291.  
  83292. #define teWordSelect 4 /*clickExpand to select word*/
  83293. æC 
  83294.  
  83295. æKY teWordDrag
  83296. æFc TextEdit.h
  83297. æT #define
  83298. æD #define teWordDrag 8 /*clickExpand to drag new word*/
  83299. æC 
  83300.  
  83301. æKY teFromFind
  83302. æFc TextEdit.h
  83303. æT #define
  83304. æD #define teFromFind 12 /*FindLine called it ($0C)*/
  83305. æC 
  83306.  
  83307. æKY teFromRecal
  83308. æFc TextEdit.h
  83309. æT #define
  83310. æD #define teFromRecal 16 /*RecalLines called it ($10)*/
  83311. æC 
  83312.  
  83313. æKY Chars
  83314. æFc TextEdit.h
  83315. æT typedef
  83316. æD typedef char Chars[32001];
  83317. typedef Chars *CharsPtr,**CharsHandle;
  83318. æC 
  83319.  
  83320. æKY TEIntHook
  83321. æFc TextEdit.h
  83322. æT typedef
  83323. æD typedef short TEIntHook;
  83324. æC 
  83325.  
  83326. æKY WordBreakProcPtr
  83327. æFc TextEdit.h
  83328. æT typedef
  83329. æD typedef pascal Boolean (*WordBreakProcPtr)(Ptr text, short charPos);
  83330. æC 
  83331.  
  83332. æKY ClikLoopProcPtr
  83333. æFc TextEdit.h
  83334. æT typedef
  83335. æD typedef pascal Boolean (*ClikLoopProcPtr)(void);
  83336. æC 
  83337.  
  83338. æKY TERec
  83339. TEPtr
  83340. TEHandle
  83341. æFc TextEdit.h
  83342. æT struct
  83343. æD struct TERec {
  83344.     Rect destRect;
  83345.     Rect viewRect;
  83346.     Rect selRect;
  83347.     short lineHeight;
  83348.     short fontAscent;
  83349.     Point selPoint;
  83350.     short selStart;
  83351.     short selEnd;
  83352.     short active;
  83353.     WordBreakProcPtr wordBreak;
  83354.     ClikLoopProcPtr clikLoop;
  83355.     long clickTime;
  83356.     short clickLoc;
  83357.     long caretTime;
  83358.     short caretState;
  83359.     short just;
  83360.     short teLength;
  83361.     Handle hText;
  83362.     short recalBack;
  83363.     short recalLines;
  83364.     short clikStuff;
  83365.     short crOnly;
  83366.     short txFont;
  83367.     Style txFace; /*txFace is unpacked byte*/
  83368.     char filler;
  83369.     short txMode;
  83370.     short txSize;
  83371.     GrafPtr inPort;
  83372.     ProcPtr highHook;
  83373.     ProcPtr caretHook;
  83374.     short nLines;
  83375.     short lineStarts[16001];
  83376. };
  83377.  
  83378. typedef struct TERec TERec;
  83379. typedef TERec *TEPtr, **TEHandle;
  83380.  
  83381. æC 
  83382. »The TERec Data Type
  83383.  
  83384. The structure of an edit record is given here. Some TextEdit features are available
  83385. only if you access fields of the edit record directly.
  83386.  
  83387. TYPE  TERec = RECORD
  83388.                 destRect:    Rect;     {destination rectangle}
  83389.                 viewRect:    Rect;     {view rectangle}
  83390.                 selRect:     Rect;     {used from assembly language}
  83391.                 lineHeight:  INTEGER;  {for line spacing}
  83392.                 fontAscent:  INTEGER;  {caret/highlighting position}
  83393.                 selPoint:    Point;    {used from assembly language}
  83394.                 selStart:    INTEGER;  {start of selection range}
  83395.                 selEnd:      INTEGER;  {end of selection range}
  83396.                 active:      INTEGER;  {used internally}
  83397.                 wordBreak:   ProcPtr;  {for word break routine}
  83398.                 clikLoop:    ProcPtr;  {for click loop routine}
  83399.                 clickTime:   LONGINT;  {used internally}
  83400.                 clickLoc:    INTEGER;  {used internally}
  83401.                 caretTime:   LONGINT;  {used internally}
  83402.                 caretState:  INTEGER;  {used internally}
  83403.                 just:        INTEGER;  {justification of text}
  83404.                 teLength:    INTEGER;  {length of text}
  83405.                 hText:       Handle;   {text to be edited}
  83406.                 recalBack:   INTEGER;  {used internally}
  83407.                 recalLines:  INTEGER;  {used internally}
  83408.                 clikStuff:   INTEGER;  {used internally}
  83409.                 crOnly:      INTEGER;  {if <0, new line at Return only}
  83410.                 txFont:      INTEGER;  {text font}
  83411.                 txFace:      Style;    {character style}
  83412.                 txMode:      INTEGER;  {pen mode}
  83413.                 txSize:      INTEGER;  {font size}
  83414.                 inPort:      GrafPtr;  {grafPort}
  83415.                 highHook:    ProcPtr;  {used from assembly language}
  83416.                 caretHook:   ProcPtr;  {used from assembly language}
  83417.                 nLines:      INTEGER;  {number of lines}
  83418.                 lineStarts:  ARRAY[0..16000] OF INTEGER
  83419.                                        {positions of line starts}
  83420.               END;
  83421.  
  83422. Warning:  Don’t change any of the fields marked “used internally”—these
  83423.           exist solely for internal use among the TextEdit routines.
  83424.  
  83425. The destRect and viewRect fields specify the destination and view rectangles.
  83426.  
  83427. The lineHeight and fontAscent fields have to do with the vertical spacing of the
  83428. lines of text, and where the caret or highlighting of the selection range is drawn
  83429. relative to the text. The fontAscent field specifies how far above the base line the
  83430. pen is positioned to begin drawing the caret or highlighting. For single-spaced text,
  83431. this is the ascent of the text in pixels (the height of the tallest characters in the
  83432. font from the base line). The lineHeight field specifies the vertical distance from
  83433. the ascent line of one line of text down to the ascent line of the next. For single-spaced
  83434. text, this is the same as the font size, but in pixels. The values of the lineHeight
  83435. and fontAscent fields for single-spaced text are shown in Figure 4. For more information
  83436. on fonts, see the Font Manager chapter.
  83437.  
  83438. •••Refer to Figure 4.•••
  83439.  
  83440. Figure 4–LineHeight and FontAscent
  83441.  
  83442. If you want to change the vertical spacing of the text, you should change both the
  83443. lineHeight and fontAscent fields by the same amount, otherwise the placement of the
  83444. caret or highlighting of the selection range may not look right. For example, to
  83445. double the line spacing, add the value of lineHeight to both fields. (This doesn’t
  83446. change the size of the characters; it affects only the spacing between lines.) If you
  83447. change the size of the text, you should also change these fields; you can get font
  83448. measurements you’ll need with the QuickDraw procedure GetFontInfo.
  83449.  
  83450. Assembly-language note:  The selPoint field (whose assembly-language offset
  83451.                          is named teSelPoint) contains the point selected
  83452.                          with the mouse, in the local coordinates of the
  83453.                          current grafPort. You’ll need this for hit-testing
  83454.                          if you use the routine pointed to by the global
  83455.                          variable TEDoText (see “Advanced Routines” in the
  83456.                          “TextEdit Routines” section).
  83457.  
  83458. The selStart and selEnd fields specify the character positions of the beginning and
  83459. end of the selection range. Remember that character position 0 refers to the first
  83460. character, and that the end of a selection range can be 1 greater than the position
  83461. of the last character of the text.
  83462.  
  83463. The wordBreak field lets you change TextEdit’s definition of a word, and the clikLoop
  83464. field lets you implement automatic scrolling. These two fields are described in
  83465. separate sections below.
  83466.  
  83467. The just field specifies the justification of the text. (See “Justification”, above.)
  83468.  
  83469. The teLength field contains the number of characters in the text to be edited
  83470. (the maximum length is 32K bytes). The hText field is a handle to the text. You can
  83471. directly change the text of an edit record by changing these two fields.
  83472.  
  83473. The crOnly field specifies whether or not text wraps around at the right edge of the
  83474. destination rectangle, as shown in Figure 5. If crOnly is positive, text does wrap
  83475. around. If crOnly is negative, text does not wrap around at the edge of the destination
  83476. rectangle, and new lines are specified explicitly by Return characters only. This is
  83477. faster than word wraparound, and is useful in an application similar to a programming-language
  83478. editor, where you may not want a single line of code to be split onto two lines.
  83479.  
  83480. •••Refer to Figure 5.•••
  83481.  
  83482. Figure 5–New Lines
  83483.  
  83484. The txFont, txFace, txMode, and txSize fields specify the font, character style, pen
  83485. mode, and font size, respectively, of all the text in the edit record. (See the
  83486. QuickDraw chapter for details about these characteristics.) If you change one of
  83487. these values, the entire text of this edit record will have the new characteristics
  83488. when it’s redrawn. If you change the txSize field, remember to change the lineHeight
  83489. and fontAscent fields, too.
  83490.  
  83491. The inPort field contains a pointer to the grafPort associated with this edit record.
  83492.  
  83493. Note:  When printing, the inPort field must be set to the Printing Manager’s
  83494.        grafPort (TPPrPort^.gPort).
  83495.  
  83496. Assembly-language note:  The highHook and caretHook fields—at the offsets
  83497.                          teHiHook and teCarHook in assembly language—contain
  83498.                          the addresses of routines that deal with text
  83499.                          highlighting and the caret. These routines pass
  83500.                          parameters in registers; the application must save
  83501.                          and restore the registers.
  83502.  
  83503.                          If you store the address of a routine in teHiHook,
  83504.                          that routine will be used instead of the QuickDraw
  83505.                          procedure InvertRect whenever a selection range is
  83506.                          to be highlighted. The routine can destroy the
  83507.                          contents of registers A0, A1, D0, D1, and D2. On
  83508.                          entry, A3 is a pointer to a locked edit record; the
  83509.                          stack contains the rectangle enclosing the text being
  83510.                          highlighted. For example, if you store the address of
  83511.                          the following routine in teHiHook, selection ranges
  83512.                          will be underlined instead of inverted:
  83513.  
  83514.                            UnderHigh
  83515.                                MOVE.L    (SP),A0            ;get address of
  83516.                                                             ; rectangle to be
  83517.                                                             ; highlighted
  83518.                                MOVE      bottom(A0),top(A0) ;make the top
  83519.                                                             ; coordinate equal
  83520.                                                             ; to the bottom
  83521.                                SUBQ      #1,top(A0)         ; coordinate - 1
  83522.                                _InverRect                   ;invert the
  83523.                                                             ; resulting
  83524.                                                             ; rectangle
  83525.                                RTS
  83526.  
  83527.                          The routine whose address is stored in teCarHook acts
  83528.                          exactly the same way as the teHiHook routine, but on
  83529.                          the caret instead of the selection highlighting,
  83530.                          allowing you to change the appearance of the caret.
  83531.                          The routine is called with the stack containing the
  83532.                          rectangle that encloses the caret.
  83533.  
  83534. The nLines field contains the number of lines in the text. The lineStarts array
  83535. contains the character position of the first character in each line. It’s declared to
  83536. have 16001 elements to comply with Pascal range checking; it’s actually a dynamic
  83537. data structure having only as many elements as needed. You shouldn’t change the
  83538. elements of lineStarts.
  83539.  
  83540. Note:  The extensions to TextEdit described in the following paragraphs were
  83541.        originally documented in Inside Macintosh, Volume V. As such, this
  83542.        information refers to the Macintosh SE and Macintosh II ROMs and System
  83543.        file version 4.1 and later.
  83544.  
  83545. In the enhanced version of TextEdit, most fields of the edit record have the same
  83546. meanings as in the old TextEdit, with the following exceptions:
  83547.  
  83548. txSize            Used as a flag telling whether the edit record has style
  83549.                   information associated with it:
  83550.  
  83551.     >0            Old-style edit record; all text set in a single font, size,
  83552.                   and face; all fields (including txSize itself) have their
  83553.                   old, natural meanings.
  83554.  
  83555.     –1            Edit record has associated style information; the txFont and
  83556.                   txFace fields have new meanings as described below.
  83557.  
  83558. txFont, txFace    Combine to hold a handle to the associated style record
  83559.                   (see “The Style Record” below).  Use new routines
  83560.                   GetStylHandle and SetStylHandle to access or change this
  83561.                   handle in Pascal.
  83562.  
  83563. lineHeight        Controls whether vertical spacing is fixed or may vary
  83564. fontAscent        from line to line, depending on specific text styles:
  83565.  
  83566.     >0            Fixed line height or font ascent, as before.
  83567.     –1            Line height or font ascent calculated independently for
  83568.                   each line, based on maximum value for any individual style
  83569.                   on that line.
  83570.  
  83571. The new routine TEStylNew, which creates a new edit record with style information,
  83572. sets txSize, lineHeight, and fontAscent to –1, allocates a style record, and stores a
  83573. handle to the style record in the txFont and txFace fields.  The old routine TENew
  83574. still creates a new edit record without style information, initializing these fields
  83575. from the current graphics port as before.
  83576.  
  83577. »The WordBreak Field
  83578.  
  83579. Note:  The information on the WordBreak Field described in the following
  83580.        paragraphs was originally documented in Inside Macintosh, Volume I.
  83581.  
  83582. The wordBreak field of an edit record lets you specify the record’s word break routine—the
  83583. routine that determines the “word” that’s highlighted when the user double-clicks in
  83584. the text, and the position at which text is wrapped around at the end of a line. The
  83585. default routine breaks words at any character with an ASCII value of $20 or less (the
  83586. space character or nonprinting control characters).
  83587.  
  83588. The word break routine must have two parameters and return a Boolean value. This is
  83589. how you would declare one named MyWordBreak:
  83590.  
  83591. FUNCTION MyWordBreak (text:  Ptr; charPos:  INTEGER) :  BOOLEAN;
  83592.  
  83593. The function should return TRUE to break a word at the character at position charPos
  83594. in the specified text, or FALSE not to break there. From Pascal, you must call the
  83595. SetWordBreak procedure to set the wordBreak field so that your routine will be used.
  83596.  
  83597. Assembly-language note:  You can set this field to point to your own
  83598.                          assembly-language word break routine. The registers
  83599.                          must contain the following:
  83600.  
  83601.                            On entry  A0:    pointer to text
  83602.                                      D0:    character position (word)
  83603.                            On exit   Z (zero) condition code:
  83604.                                        0 to break at specified character
  83605.                                        1 not to break there
  83606.  
  83607. »The ClikLoop Field
  83608.  
  83609. The clikLoop field of an edit record lets you specify a routine that will be called
  83610. repeatedly (by the TEClick procedure, described below) as long as the mouse button is
  83611. held down within the text. You can use this to implement the automatic scrolling of
  83612. text when the user is making a selection and drags the cursor out of the view rectangle.
  83613.  
  83614. The click loop routine has no parameters and returns a Boolean value. You could
  83615. declare a click loop routine named MyClikLoop like this:
  83616.  
  83617. FUNCTION MyClikLoop :  BOOLEAN;
  83618.  
  83619. The function should return TRUE. From Pascal, you must call the SetClikLoop procedure
  83620. to set the clikLoop field so that TextEdit will call your routine.
  83621.  
  83622. Warning:  Returning FALSE from your click loop routine tells the TEClick
  83623.           procedure that the mouse button has been released, which aborts
  83624.           TEClick.
  83625.  
  83626. Assembly-language note:  Your routine should set register D0 to 1, and
  83627.                          preserve register D2. (Returning 0 in register
  83628.                          D0 aborts TEClick.)
  83629.  
  83630. An automatic scrolling routine might check the mouse location, and call a scrolling
  83631. routine if the mouse location is outside the view rectangle. (The scrolling routine
  83632. can be the same routine that the Control Manager function TrackControl calls.) The
  83633. handle to the current edit record should be kept as a global variable so the scrolling
  83634. routine can access it.
  83635.  
  83636. æKY StyleRun
  83637. æFc TextEdit.h
  83638. æT struct
  83639. æD struct StyleRun {
  83640.     short startChar; /*starting character position*/
  83641.     short styleIndex; /*index in style table*/
  83642. };
  83643.  
  83644. typedef struct StyleRun StyleRun;
  83645. æC 
  83646.  
  83647. æKY STElement
  83648. æFc TextEdit.h
  83649. æT struct
  83650. æD struct STElement {
  83651.     short stCount; /*number of runs in this style*/
  83652.     short stHeight; /*line height*/
  83653.     short stAscent; /*font ascent*/
  83654.     short stFont; /*font (family) number*/
  83655.     Style stFace; /*character Style*/
  83656.     char filler; /*stFace is unpacked byte*/
  83657.     short stSize; /*size in points*/
  83658.     RGBColor stColor; /*absolute (RGB) color*/
  83659. };
  83660.  
  83661. typedef struct STElement STElement;
  83662. typedef STElement TEStyleTable[1777], *STPtr, **STHandle;
  83663.  
  83664. æC 
  83665. »The Style Table
  83666.  
  83667. The style table contains one entry for each distinct style used in an edit record’s
  83668. text.  The size of the table is given by the nStyles field of the style record. 
  83669. There is no duplication; each style appears exactly once in the table.  A reference
  83670. count tells how many times each style is used within the text.
  83671.  
  83672. TYPE
  83673.   STHandle      = ^STPtr;
  83674.   STPtr         = ^TEStyleTable;
  83675.   TEStyleTable  = ARRAY [0..0] OF STElement;
  83676.   STElement     = RECORD
  83677.                     stCount:   INTEGER;    {number of runs in this style}
  83678.                     stHeight:  INTEGER;    {line height}
  83679.                     stAscent:  INTEGER;    {font ascent}
  83680.                     stFont:    INTEGER;    {font (family) number}
  83681.                     stFace:    Style;      {character style}
  83682.                     stSize:    INTEGER;    {size in points}
  83683.                     stColor:   RGBColor    {absolute (RGB) color}
  83684.                   END;
  83685.  
  83686. Field descriptions
  83687.  
  83688. stCount     The stCount field contains a reference count of character
  83689.             runs using this style.
  83690. stHeight    The stHeight field contains the line height for this style,
  83691.             in points.
  83692. stAscent    The stAscent field contains the font ascent for this style,
  83693.             in points.
  83694. stFont      The stFont field is the font (family) number.
  83695. stFace      The stFace field is the character style (bold, italic, and
  83696.             so forth).
  83697. stSize      The stSize field is the text size in points.
  83698. stColor     The stColor field is the RGB color; see the Color Manager
  83699.             chapter for further information.
  83700.  
  83701. æKY LHElement
  83702. æFc TextEdit.h
  83703. æT struct
  83704. æD struct LHElement {
  83705.     short lhHeight; /*maximum height in line*/
  83706.     short lhAscent; /*maximum ascent in line*/
  83707. };
  83708.  
  83709. typedef struct LHElement LHElement;
  83710. typedef LHElement LHTable[8001], *LHPtr, **LHHandle; /* ARRAY [0..8000] OF LHElement */
  83711.  
  83712. æC 
  83713. »The Line-Height Table
  83714.  
  83715. The line-height table holds vertical spacing information for an edit record’s text. 
  83716. This table parallels the lineStarts table in the edit record itself. Its length is
  83717. given by the edit record’s nLines field plus 1 for a dummy entry at the end, just as
  83718. the line starts array ends with a dummy entry that has the same value as the length
  83719. of the text. The table’s contents are recalculated whenever the line starts themselves
  83720. are recalculated with TECalText, or whenever an editing action causes recalibration.
  83721.  
  83722. The line-height table is used only if the lineHeight and fontAscent fields in the
  83723. edit record are negative; positive values in those fields specify fixed vertical
  83724. spacing, overriding the information in the table.
  83725.  
  83726. TYPE
  83727.   LHHandle   = ^LHPtr;
  83728.   LHPtr      = ^LHTable;
  83729.   LHTable    = ARRAY [0..0] OF LHElement;
  83730.   LHElement  = RECORD
  83731.                  lhHeight:    INTEGER;    {maximum height in line}
  83732.                  lhAscent:    INTEGER     {maximum ascent in line}
  83733.           END;
  83734.  
  83735. Field descriptions
  83736.  
  83737. lhHeight    The lhHeight field contains the line height in points;
  83738.             this is the maximum value for any individual style in a line.
  83739.  
  83740. lhAscent    The lhAscent field contains the font ascent in points;
  83741.             this is the maximum value for any individual style in a line.
  83742.  
  83743. If you want, you can override TextEdit’s line-height calculation and store your own
  83744. height and ascent values into the line-height table.  Any table entry with the high
  83745. bit set in the lhHeight field will be used as-is (both height and ascent), overriding
  83746. whatever values TextEdit would have used.  The high bit of lhHeight is masked out to
  83747. arrive at the true line height, but the high bit of lhAscent is not masked, so you
  83748. should never set it; the one in lhHeight serves as a flag for both fields.  Notice
  83749. that you can selectively set some lines for yourself and let TextEdit do the rest for
  83750. you.  This technique is intended to be used for static, unchanging text, such as in
  83751. text boxes; if you use it on text that can change dynamically, be sure to readjust
  83752. your line-height values whenever the line breaks in the text are recalculated. Otherwise,
  83753. if new lines are created as a result of a text insertion, their line heights and
  83754. ascents will be computed by TextEdit.
  83755.  
  83756. æKY ScrpSTElement
  83757. æFc TextEdit.h
  83758. æT struct
  83759. æD struct ScrpSTElement {
  83760.     long scrpStartChar; /*starting character position*/
  83761.     short scrpHeight; /*starting character position*/
  83762.     short scrpAscent;
  83763.     short scrpFont;
  83764.     Style scrpFace; /*unpacked byte*/
  83765.     char filler; /*scrpFace is unpacked byte*/
  83766.     short scrpSize;
  83767.     RGBColor scrpColor;
  83768. };
  83769.  
  83770. typedef struct ScrpSTElement ScrpSTElement;
  83771. typedef ScrpSTElement ScrpSTTable[1601]; /* ARRAY [0..1600] OF ScrpSTElement */
  83772.  
  83773. æC 
  83774. The ScrpSTTable is a separate data structure defined for style records in the scrap.
  83775. Its format is:
  83776.  
  83777. TYPE
  83778.   ScrpSTTable    = array [0..0] of ScrpSTElement;
  83779.   ScrpSTElement  = RECORD
  83780.                      scrpStartChar:  LONGINT;    {offset to start of style}
  83781.                      scrpHeight:     INTEGER;    {line height}
  83782.                      scrpAscent:     INTEGER;    {font ascent}
  83783.                      scrpFont:       INTEGER;    {font (family) number}
  83784.                      scrpFace:       Style;      {character style}
  83785.                      scrpSize:       INTEGER;    {size in points}
  83786.                      scrpColor:      RGBColor;   {absolute (RGB) color}
  83787.                    END;
  83788.  
  83789. Field descriptions
  83790.  
  83791. scrpStartChar    The scrpStartChar field is the offset to the beginning
  83792.                  of a style record in the scrap.
  83793. scrpHeight       The scrpHeight field contains the line height.
  83794. scrpAscent       The scrpAscent field contains the font ascent.
  83795. scrpFont         The scrpFont is the font’s family number.
  83796. scrpFace         The scrpFace is the character style for the style scrap.
  83797. scrpSize         The scrpSize field contains the size in points.
  83798. scrpColor        The scrpColor field contains the RGB color for the style scrap.
  83799.  
  83800. æKY StScrpRec
  83801. StScrpPtr
  83802. StScrpHandle
  83803. æFc TextEdit.h
  83804. æT struct
  83805. æD struct StScrpRec {
  83806.     short scrpNStyles; /*number of styles in scrap*/
  83807.     ScrpSTTable scrpStyleTab; /*table of styles for scrap*/
  83808. };
  83809.  
  83810. typedef struct StScrpRec StScrpRec;
  83811. typedef StScrpRec *StScrpPtr, **StScrpHandle;
  83812.  
  83813. æC 
  83814. »The Style Scrap
  83815.  
  83816. A new scrap type, 'styl', is used for storing style information in the desk scrap
  83817. along with the old 'TEXT' scrap. The format of the style scrap is defined by a style
  83818. scrap record:
  83819.  
  83820. TYPE
  83821.   StScrpHandle  = ^StScrpPtr;
  83822.   StScrpPtr     = ^StScrpRec;
  83823.   StScrpRec     = RECORD
  83824.                     scrpNStyles:    INTEGER;       {number of distinct }
  83825.                                                    { styles in scrap}
  83826.                     scrpStyleTab:   ScrpSTTable    {table of styles for scrap}
  83827.                   END;
  83828.  
  83829. Field descriptions
  83830.  
  83831. scrpNStyles    The scrpNStyles field is the number of distinct styles
  83832.                used in text; this forms the size of the style table.
  83833.  
  83834. scrpSTTable    The scrpSTTable is the table of text styles: see the data
  83835.                structure shown below.
  83836.  
  83837. Unlike the main style table for an edit record, the table in the style scrap may
  83838. contain duplicate elements; the entries in the table correspond one-to-one with the
  83839. character runs in the text.  The scrpStartChar field of each entry gives the starting
  83840. character position for the run.
  83841.  
  83842. The ScrpSTTable is a separate data structure defined for style records in the scrap.
  83843. Its format is:
  83844.  
  83845. TYPE
  83846.   ScrpSTTable    = array [0..0] of ScrpSTElement;
  83847.   ScrpSTElement  = RECORD
  83848.                      scrpStartChar:  LONGINT;    {offset to start of style}
  83849.                      scrpHeight:     INTEGER;    {line height}
  83850.                      scrpAscent:     INTEGER;    {font ascent}
  83851.                      scrpFont:       INTEGER;    {font (family) number}
  83852.                      scrpFace:       Style;      {character style}
  83853.                      scrpSize:       INTEGER;    {size in points}
  83854.                      scrpColor:      RGBColor;   {absolute (RGB) color}
  83855.                    END;
  83856.  
  83857. Field descriptions
  83858.  
  83859. scrpStartChar    The scrpStartChar field is the offset to the beginning
  83860.                  of a style record in the scrap.
  83861. scrpHeight       The scrpHeight field contains the line height.
  83862. scrpAscent       The scrpAscent field contains the font ascent.
  83863. scrpFont         The scrpFont is the font’s family number.
  83864. scrpFace         The scrpFace is the character style for the style scrap.
  83865. scrpSize         The scrpSize field contains the size in points.
  83866. scrpColor        The scrpColor field contains the RGB color for the style scrap.
  83867.  
  83868. æKY NullStRec
  83869. NullStPtr
  83870. NullStHandle
  83871. æFc TextEdit.h
  83872. æT struct
  83873. æD struct NullStRec {
  83874.     long teReserved; /*reserved for future expansion*/
  83875.     StScrpHandle nullScrap; /*handle to scrap style table*/
  83876. };
  83877.  
  83878. typedef struct NullStRec NullStRec;
  83879. typedef NullStRec *NullStPtr, **NullStHandle;
  83880.  
  83881. æC 
  83882. »The Null-Style Record
  83883.  
  83884. The null-style record is used to store the style information for a null selection. If
  83885. TESetStyle is called when setStart equals setEnd, the input style information is
  83886. stored in the nullStyle handle. The nStyles field of nullScrap is set to 1, and the
  83887. style information is stored as the ScrpSTElement. If text is then entered (pasted,
  83888. inserted, or typed), the style is entered into the runs array, and nStyles is reset
  83889. to 0. The nStyles field is also reset if the selection offsets are changed (by TEClick,
  83890. for example).
  83891.  
  83892. TYPE
  83893.   NullSTHandle  = ^NullSTPtr;
  83894.   NullSTPtr     = ^NullSTRec;
  83895.   NullSTRec     = RECORD
  83896.                     TEReserved:   LONGINT;        {reserved for future }
  83897.                                                   { expansion}
  83898.                     nullScrap:    STScrpHandle    {handle to scrap style }
  83899.                                                   { table}
  83900.                   END;
  83901.  
  83902. Field descriptions
  83903.  
  83904. teReserved    The teReserved field is reserved for future expansion.
  83905.  
  83906. nullScrap     The nullScrap field contains a handle to the scrap style table.
  83907.  
  83908. æKY TEStyleRec
  83909. TEStylePtr
  83910. TEStyleHandle
  83911. æFc TextEdit.h
  83912. æT struct
  83913. æD struct TEStyleRec {
  83914.     short nRuns; /*number of style runs*/
  83915.     short nStyles; /*size of style table*/
  83916.     STHandle styleTab; /*handle to style table*/
  83917.     LHHandle lhTab; /*handle to line-height table*/
  83918.     long teRefCon; /*reserved for application use*/
  83919.     NullStHandle nullStyle; /*Handle to style set at null selection*/
  83920.     StyleRun runs[8001]; /*ARRAY [0..8000] OF StyleRun*/
  83921. };
  83922.  
  83923. typedef struct TEStyleRec TEStyleRec;
  83924. typedef TEStyleRec *TEStylePtr, **TEStyleHandle;
  83925.  
  83926. æC 
  83927. »The Style Record
  83928.  
  83929. Note:  The extensions to TextEdit described in the following paragraphs were
  83930.        originally documented in Inside Macintosh, Volume V. As such, this
  83931.        information refers to the Macintosh SE and Macintosh II ROMs and System
  83932.        file version 4.1 and later.
  83933.  
  83934. The style record, located via a handle kept in the txFont and txFace fields of the
  83935. edit record, specifies the styles for the edit record’s text.  The text is divided
  83936. into runs of consecutive characters in the same style, summarized in a table in the
  83937. runs field of the style record.  Each entry in this table gives the starting character
  83938. position of a run and an index into the style table
  83939. (described in the next section).  The length of the run is found by subtracting its
  83940. start position from that of the next entry in the table.  A dummy entry at the end of
  83941. the table delimits the length of the last run; its start position is equal to the
  83942. overall number of characters in the text, plus 1.
  83943.  
  83944. TYPE
  83945.   TEStyleHandle  = ^TEStylePtr;
  83946.   TEStylePtr     = ^TEStyleRec;
  83947.   TEStyleRec     = RECORD
  83948.                      nRuns:      INTEGER;       {number of style runs}
  83949.                      nStyles:    INTEGER;       {number of distinct styles }
  83950.                                                 { stored in style table}
  83951.                      styleTab:   STHandle;      {handle to style table}
  83952.                      lhTab:      LHHandle;      {handle to line-height table}
  83953.                      teRefCon:   LONGINT;       {reserved for application use}
  83954.                      nullStyle:  nullSTHandle;  {handle to style set }
  83955.                                                 { at null selection}
  83956.                      runs:       ARRAY [0..0] OF StyleRun
  83957.                    END;
  83958.  
  83959.   StyleRun = RECORD
  83960.                startChar:  INTEGER;  {starting character position}
  83961.                styleIndex: INTEGER   {index in style table}
  83962.         END;
  83963.  
  83964. Field descriptions
  83965.  
  83966. nRuns        The nRuns field specifies the number of style runs in the text.
  83967. nStyles      The nStyles field contains the number of distinct styles used
  83968.              in the text; this forms the size of the style table.
  83969. styleTab     The StyleTab field contains a handle to the style table (see
  83970.              “The Style Table” below).
  83971. lhTab        The lhTab field contains a handle to the line-height table
  83972.              (see “The Line-Height Table” below).
  83973. teRefCon     The teRefCon field is a reference constant for use by applications.
  83974. nullStyle    The nullStyle field contains a handle to a data structure used
  83975.              to store the style information for a null selection.
  83976. runs         The runs field contains an indefinite-length array of style runs.
  83977.  
  83978. æKY TextStyle
  83979. TextStylePtr
  83980. TextStyleHandle
  83981. æFc TextEdit.h
  83982. æT struct
  83983. æD struct TextStyle {
  83984.     short tsFont; /*font (family) number*/
  83985.     Style tsFace; /*character Style*/
  83986.     char filler; /*tsFace is unpacked byte*/
  83987.     short tsSize; /*size in point*/
  83988.     RGBColor tsColor; /*absolute (RGB) color*/
  83989. };
  83990.  
  83991. typedef struct TextStyle TextStyle;
  83992. typedef TextStyle *TextStylePtr, **TextStyleHandle;
  83993.  
  83994. æC 
  83995. »Text Styles
  83996.  
  83997. Text style records are used for communicating style information between the application
  83998. program and the TextEdit routines.  They carry the same information as the STElement
  83999. records in the style table, but without the reference count, line height, and font
  84000. ascent:
  84001.  
  84002. TYPE
  84003.   TextStyle = RECORD
  84004.                 tsFont:    INTEGER;    {Font (family) number}
  84005.                 tsFace:    Style;      {Character style}
  84006.                 tsSize:    INTEGER;    {Size in points}
  84007.                 tsColor:   RGBColor    {Absolute (RGB) color}
  84008.               END;
  84009.  
  84010. Field descriptions
  84011.  
  84012. tsFont     The tsFont field is the font (family) number.
  84013. tsFace     The tsFace field is the character style (bold, italic, and so forth).
  84014. tsSize     The tsSize field is the text size in points.
  84015. tsColor    The tsColor field contains the RGB color; see the Color Manager
  84016.            chapter for further information.
  84017.  
  84018. æKY TEInit
  84019. æFc TextEdit.h
  84020. æT Function
  84021. æTN A9CC
  84022. æD pascal void TEInit(void)
  84023.     = 0xA9CC; 
  84024. æDT TEInit()(void);
  84025. æMM
  84026. æRI I-383, P-107, 118, 183
  84027. æC  
  84028. _______________________________________________________________________________
  84029.  
  84030. »TEXTEDIT ROUTINES
  84031. _______________________________________________________________________________
  84032.  
  84033. Note:  The information on TextEdit Routines described in the following
  84034.        paragraphs was originally documented in Inside Macintosh, Volume I.
  84035.        Those routines which were added with Styled TextEdit in Volume V
  84036.        are marked as such.
  84037.  
  84038. The Macintosh Plus, Macintosh SE, and Macintosh II versions of TextEdit support all
  84039. previous TextEdit routines, as well as the new routines described below.
  84040.  
  84041. Assembly-language note:  All but two of the new routines share a single
  84042.                          trap, _TEDispatch ($A83D).  The routines are
  84043.                          distinguished by an integer routine selector
  84044.                          passed on the stack, after the last argument:
  84045.  
  84046.                            TEStylPaste     0
  84047.                            TESetStyle      1
  84048.                            TEReplaceStyle  2
  84049.                            TEGetStyle      3
  84050.                            GetStylHandle   4
  84051.                            SetStylHandle   5
  84052.                            GetStylScrap    6
  84053.                            TEStylInsert    7
  84054.                            TEGetPoint      8
  84055.                            TEGetHeight     9
  84056.  
  84057.                          The Pascal interface supplies the routine selectors
  84058.                          automatically, as do the macros for calling these
  84059.                          routines from assembly language.  The remaining two
  84060.                          new TextEdit routines have traps of their own:
  84061.                          _TEStylNew ($A83E) and _TEGetOffset ($A83C).
  84062.  
  84063. »Initialization and Allocation
  84064.  
  84065. PROCEDURE TEInit;
  84066.  
  84067. TEInit initializes TextEdit by allocating a handle for the TextEdit scrap. The scrap
  84068. is initially empty. Call this procedure once and only once at the beginning of your
  84069. program.
  84070.  
  84071. Note:  You should call TEInit even if your application doesn’t use TextEdit,
  84072.        so that desk accessories and dialog and alert boxes will work correctly.
  84073.  
  84074. æKY TENew
  84075. æFc TextEdit.h
  84076. æT Function
  84077. æTN A9D2
  84078. æD pascal TEHandle TENew(const Rect *destRect,const Rect *viewRect)
  84079.     = 0xA9D2; 
  84080. æDT TEHandle myVariable = TENew((const Rect *) destRect,(const Rect *) viewRect);
  84081. æMM
  84082. æRI I-383, P-118, 183
  84083. æC 
  84084. TENew allocates a handle for text, creates and initializes an edit record, and returns
  84085. a handle to the new edit record. DestRect and viewRect are the destination and view
  84086. rectangles, respectively. Both rectangles are specified in the current grafPort’s
  84087. coordinates. The destination rectangle must always be at least as wide as the first
  84088. character drawn (about 20 pixels is a good minimum width). The view rectangle must
  84089. not be empty (for example, don’t make its right edge less than its left edge if you
  84090. don’t want any text visible—specify a rectangle off the screen instead).
  84091.  
  84092. Call TENew once for every edit record you want allocated. The edit record incorporates
  84093. the drawing environment of the grafPort, and is initialized for left-justified,
  84094. single-spaced text with an insertion point at character position 0.
  84095.  
  84096. Note:  The caret won’t appear until you call TEActivate.
  84097.  
  84098. æKY TEDispose
  84099. æFc TextEdit.h
  84100. æT Function
  84101. æTN A9CD
  84102. æD pascal void TEDispose(TEHandle hTE)
  84103.     = 0xA9CD; 
  84104. æDT TEDispose((TEHandle) hTE);
  84105. æMM
  84106. æRI I-383, P-118, 183
  84107. æC 
  84108. TEDispose releases the memory allocated for the edit record and text specified by
  84109. hTE. Call this procedure when you’re completely through with an edit record.
  84110.  
  84111. æKY TESetText
  84112. æFc TextEdit.h
  84113. æT Function
  84114. æTN A9CF
  84115. æD pascal void TESetText(Ptr text,long length,TEHandle hTE)
  84116.     = 0xA9CF; 
  84117. æDT TESetText((Ptr) text,(long) length,(TEHandle) hTE);
  84118. æMM
  84119. æRI I-383, N18-1
  84120. æC 
  84121. TESetText incorporates a copy of the specified text into the edit record specified by
  84122. hTE. The text parameter points to the text, and the length parameter indicates the
  84123. number of characters in the text. The selection range is set to an insertion point at
  84124. the end of the text. TESetText doesn’t affect the text drawn in the destination
  84125. rectangle, so call InvalRect afterward if necessary. TESetText doesn’t dispose of any
  84126. text currently in the edit record.
  84127.  
  84128. æKY TEGetText
  84129. æFc TextEdit.h
  84130. æT Function
  84131. æTN A9CB
  84132. æD pascal CharsHandle TEGetText(TEHandle hTE)
  84133.     = 0xA9CB; 
  84134. æDT CharsHandle myVariable = TEGetText((TEHandle) hTE);
  84135. æMM
  84136. æRI I-384
  84137. æC  
  84138. TEGetText returns a handle to the text of the specified edit record. The result is
  84139. the same as the handle in the hText field of the edit record, but has the CharsHandle
  84140. data type, which is defined as:
  84141.  
  84142. TYPE  CharsHandle  = ^CharsPtr;
  84143.       CharsPtr     = ^Chars;
  84144.       Chars        = PACKED ARRAY[0..32000] OF CHAR;
  84145.  
  84146. You can get the length of the text from the teLength field of the edit record.
  84147.  
  84148. æKY TEIdle
  84149. æFc TextEdit.h
  84150. æT Function
  84151. æTN A9DA
  84152. æD pascal void TEIdle(TEHandle hTE)
  84153.     = 0xA9DA; 
  84154. æDT TEIdle((TEHandle) hTE);
  84155. æMM
  84156. æRI I-384
  84157. æC 
  84158. Call TEIdle repeatedly to make a blinking caret appear at the insertion point
  84159. (if any) in the text specified by hTE. (The caret appears only when the window containing
  84160. that text is active, of course.) TextEdit observes a minimum blink interval:  No
  84161. matter how often you call TEIdle, the time between blinks will never be less than the
  84162. minimum interval.
  84163.  
  84164. Note:  The initial minimum blink interval setting is 32 ticks. The user
  84165.        can adjust this setting with the Control Panel desk accessory.
  84166.  
  84167. To provide a constant frequency of blinking, you should call TEIdle as often as
  84168. possible—at least once each time through your main event loop. Call it more than once
  84169. if your application does an unusually large amount of processing each time through
  84170. the loop.
  84171.  
  84172. Note:  You actually need to call TEIdle only when the window containing
  84173.        the text is active.
  84174.  
  84175. æKY TESetSelect
  84176. æFc TextEdit.h
  84177. æT Function
  84178. æTN A9D1
  84179. æD pascal void TESetSelect(long selStart,long selEnd,TEHandle hTE)
  84180.     = 0xA9D1; 
  84181. æDT TESetSelect((long) selStart,(long) selEnd,(TEHandle) hTE);
  84182. æMM
  84183. æRT 127
  84184. æRI I-385, N127
  84185. æC 
  84186. TESetSelect sets the selection range to the text between selStart and selEnd in the
  84187. text specified by hTE. The old selection range is unhighlighted, and the new one is
  84188. highlighted. If selStart equals selEnd, the selection range is an insertion point,
  84189. and a caret is displayed.
  84190.  
  84191. SelEnd and selStart can range from 0 to 32767. If selEnd is anywhere beyond the last
  84192. character of the text, the position just past the last character is used.
  84193.  
  84194. æKY TEActivate
  84195. æFc TextEdit.h
  84196. æT Function
  84197. æTN A9D8
  84198. æD pascal void TEActivate(TEHandle hTE)
  84199.     = 0xA9D8; 
  84200. æDT TEActivate((TEHandle) hTE);
  84201. æMM
  84202. æRI I-385
  84203. æC 
  84204. TEActivate highlights the selection range in the view rectangle of the edit record
  84205. specified by hTE. If the selection range is an insertion point, it displays a caret
  84206. there. This procedure should be called every time the Toolbox Event Manager function
  84207. GetNextEvent reports that the window containing the edit record has become active.
  84208.  
  84209. æKY TEDeactivate
  84210. æFc TextEdit.h
  84211. æT Function
  84212. æTN A9D9
  84213. æD pascal void TEDeactivate(TEHandle hTE)
  84214.     = 0xA9D9; 
  84215. æDT TEDeactivate((TEHandle) hTE);
  84216. æMM
  84217. æRI I-385
  84218. æC  
  84219. TEDeactivate unhighlights the selection range in the view rectangle of the edit
  84220. record specified by hTE. If the selection range is an insertion point, it removes the
  84221. caret. This procedure should be called every time the Toolbox Event Manager function
  84222. GetNextEvent reports that the window containing the edit record has become inactive.
  84223.  
  84224. æKY TEKey
  84225. æFc TextEdit.h
  84226. æT Function
  84227. æTN A9DC
  84228. æD pascal void TEKey(short key,TEHandle hTE)
  84229.     = 0xA9DC; 
  84230. æDT TEKey((short) key,(TEHandle) hTE);
  84231. æMM
  84232. æRT 207
  84233. æRI I-385, P-119, 183, VI
  84234. æC 
  84235. TEKey was modified in system software version 6.0 so that it no longer deletes a
  84236. style if the user backspaces to the beginning of a style. Instead, TEKey saves
  84237. the style in the nullScrap field of the NullSTRec to be applied to subsequent
  84238. typed characters. As soon as the user backspaces past the beginning of the 
  84239. style, or clicks in another area of the text, TEKey removes the style.
  84240.  
  84241. Note:  Currently, TEKey does not support the use of modifier keys, such as the
  84242. Shift key, to extend word selection. 
  84243.  
  84244. æKY TECut
  84245. æFc TextEdit.h
  84246. æT Function
  84247. æTN A9D6
  84248. æD pascal void TECut(TEHandle hTE)
  84249.     = 0xA9D6; 
  84250. æDT TECut((TEHandle) hTE);
  84251. æMM
  84252. æRT 207
  84253. æRI I-385, P-119, 182
  84254. æC 
  84255. TECut removes the selection range from the text specified by hTE and places it in the
  84256. TextEdit scrap. The text is redrawn as necessary. Anything previously in the scrap is
  84257. deleted. (See Figure 6.) If the selection range is an insertion point, the scrap is
  84258. emptied.
  84259.  
  84260. •••Refer to Figure 6.•••
  84261.  
  84262. Figure 6–Cutting
  84263.  
  84264. æKY TECopy
  84265. æFc TextEdit.h
  84266. æT Function
  84267. æTN A9D5
  84268. æD pascal void TECopy(TEHandle hTE)
  84269.     = 0xA9D5; 
  84270. æDT TECopy((TEHandle) hTE);
  84271. æMM
  84272. æRT 207
  84273. æRI I-386, P-119, 182
  84274. æC 
  84275. TECopy copies the selection range from the text specified by hTE into the TextEdit
  84276. scrap. Anything previously in the scrap is deleted. The selection range is not deleted.
  84277. If the selection range is an insertion point, the scrap is emptied.
  84278.  
  84279. æKY TEPaste
  84280. æFc TextEdit.h
  84281. æT Function
  84282. æTN A9DB
  84283. æD pascal void TEPaste(TEHandle hTE)
  84284.     = 0xA9DB; 
  84285. æDT TEPaste((TEHandle) hTE);
  84286. æMM
  84287. æRI I-386, P-119, 183
  84288. æC 
  84289. TEPaste replaces the selection range in the text specified by hTE with the contents
  84290. of the TextEdit scrap, and leaves an insertion point just past the inserted text.
  84291. (See Figure 7.) The text is redrawn as necessary. If the scrap is empty, the selection
  84292. range is deleted. If the selection range is an insertion point, TEPaste just inserts
  84293. the scrap there.
  84294.  
  84295. •••Refer to Figure 7.•••
  84296.  
  84297. Figure 7–Cutting and Pasting
  84298.  
  84299. æKY TEDelete
  84300. æFc TextEdit.h
  84301. æT Function
  84302. æTN A9D7
  84303. æD pascal void TEDelete(TEHandle hTE)
  84304.     = 0xA9D7; 
  84305. æDT TEDelete((TEHandle) hTE);
  84306. æMM
  84307. æRT 207
  84308. æRI I-387, P-119, 182
  84309. æC 
  84310. TEDelete removes the selection range from the text specified by hTE, and redraws the
  84311. text as necessary. TEDelete is the same as TECut (above) except that it doesn’t
  84312. transfer the selection range to the scrap. If the selection range is an insertion
  84313. point, nothing happens.
  84314.  
  84315. æKY TEInsert
  84316. æFc TextEdit.h
  84317. æT Function
  84318. æTN A9DE
  84319. æD pascal void TEInsert(Ptr text,long length,TEHandle hTE)
  84320.     = 0xA9DE; 
  84321. æDT TEInsert((Ptr) text,(long) length,(TEHandle) hTE);
  84322. æMM
  84323. æRI I-387, P-120, 183
  84324. æC 
  84325. TEInsert takes the specified text and inserts it just before the selection range into
  84326. the text indicated by hTE, redrawing the text as necessary. The text parameter points
  84327. to the text to be inserted, and the length parameter indicates the number of characters
  84328. to be inserted. TEInsert doesn’t affect either the current selection range or the
  84329. scrap.
  84330.  
  84331. æKY TESetJust
  84332. æFc TextEdit.h
  84333. æT Function
  84334. æTN A9DF
  84335. æD pascal void TESetJust(short just,TEHandle hTE)
  84336.     = 0xA9DF; 
  84337. æDT TESetJust((short) just,(TEHandle) hTE);
  84338. æMM
  84339. æRI I-387
  84340. æC 
  84341. TESetJust sets the justification of the text specified by hTE to just. TextEdit
  84342. provides three predefined constants for setting justification:
  84343.  
  84344. CONST  teJustLeft    = 0;
  84345.        teJustCenter  = 1;
  84346.        teJustRight   = -1;
  84347.  
  84348. By default, text is left-justified. If you change the justification, call InvalRect
  84349. after TESetJust, so the text will be redrawn with the new justification.
  84350.  
  84351. æKY TEUpdate
  84352. æFc TextEdit.h
  84353. æT Function
  84354. æTN A9D3
  84355. æD pascal void TEUpdate(const Rect *rUpdate,TEHandle hTE)
  84356.     = 0xA9D3; 
  84357. æDT TEUpdate((const Rect *) rUpdate,(TEHandle) hTE);
  84358. æMM
  84359. æRI I-387
  84360. æC 
  84361. TEUpdate draws the text specified by hTE within the rectangle specified by rUpdate
  84362. (given in the coordinates of the current grafPort). Call TEUpdate every time the
  84363. Toolbox Event Manager function GetNextEvent reports an update event for a text editing
  84364. window—after you call the Window Manager procedure BeginUpdate, and before you call
  84365. EndUpdate.
  84366.  
  84367. Normally you’ll do the following when an update event occurs:
  84368.  
  84369.   BeginUpdate(myWindow);
  84370.   EraseRect(myWindow^.portRect);
  84371.   TEUpdate(myWindow^.portRect,hTE);
  84372.   EndUpdate(myWindow)
  84373.  
  84374. If you don’t include the EraseRect call, the caret may sometimes remain visible when
  84375. the window is deactivated.
  84376.  
  84377. æKY TextBox
  84378. æFc TextEdit.h
  84379. æT Function
  84380. æTN A9CE
  84381. æD pascal void TextBox(Ptr text,long length,const Rect *box,short just)
  84382.     = 0xA9CE; 
  84383. æDT TextBox((Ptr) text,(long) length,(const Rect *) box,(short) just);
  84384. æMM
  84385. æRT 72, 207
  84386. æRI I-388, P-115, 183
  84387. æC 
  84388. TextBox draws the specified text in the rectangle indicated by the box parameter,
  84389. with justification just. (See “Justification” under “Edit Records”.) The text parameter
  84390. points to the text, and the length parameter indicates the number of characters to
  84391. draw. The rectangle is specified in local coordinates, and must be at least as wide
  84392. as the first character drawn (a good rule of thumb is to make it at least 20 pixels
  84393. wide). TextBox creates its own edit record, which it deletes when it’s finished with
  84394. it, so the text it draws cannot be edited.
  84395.  
  84396. For example:
  84397.  
  84398.   str := 'String in a box';
  84399.   SetRect(r,100,100,200,200);
  84400.   TextBox(POINTER(ORD(@str)+1),LENGTH(str),r,teJustCenter);
  84401.   FrameRect(r)
  84402.  
  84403. Because Pascal strings start with a length byte, you must advance the pointer one
  84404. position past the beginning of the string to point to the start of the text.
  84405.  
  84406. æKY TEScroll
  84407. æFc TextEdit.h
  84408. æT Function
  84409. æTN A9DD
  84410. æD pascal void TEScroll(short dh,short dv,TEHandle hTE)
  84411.     = 0xA9DD; 
  84412. æDT TEScroll((short) dh,(short) dv,(TEHandle) hTE);
  84413. æMM
  84414. æRT 22, 131
  84415. æRI I-388, N22-1, N131-3, P-120
  84416. æC 
  84417. TEScroll scrolls the text within the view rectangle of the specified edit record by
  84418. the number of pixels specified in the dh and dv parameters. The edit record is specified
  84419. by the hTE parameter. Positive dh and dv values move the text right and down, respectively,
  84420. and negative values move the text left and up. For example,
  84421.  
  84422.   TEScroll(0,-hTE^^.lineHeight,hTE)
  84423.  
  84424. scrolls the text up one line. Remember that you scroll text up when the user clicks
  84425. in the scroll arrow pointing down. The destination rectangle is offset by the amount
  84426. you scroll.
  84427.  
  84428. Note:  To implement automatic scrolling, you store the address of a routine
  84429.        in the clikLoop field of the edit record, as described above under
  84430.        “The TERec Data Type”.
  84431.  
  84432. æKY TESelView
  84433. æFc TextEdit.h
  84434. æT Function
  84435. æTN A811
  84436. æD pascal void TESelView(TEHandle hTE)
  84437.     = 0xA811; 
  84438. æDT TESelView((TEHandle) hTE);
  84439. æMM
  84440. æRI IV-57
  84441. æC 
  84442. [Volume IV addition]
  84443.  
  84444. If automatic scrolling has been enabled (by a call to TEAutoView, described below),
  84445. TESelView makes sure that the selection range is visible, scrolling it into the view
  84446. rectangle if necessary. If automatic scrolling is disabled, TESelView does nothing.
  84447.  
  84448. Note:  The top left of the insertion is scrolled into view; if text is
  84449.        being displayed in a rectangle that’s not tall enough, automatic
  84450.        scrolling could cause the text to jump up and down at times.
  84451.  
  84452. æKY TEPinScroll
  84453. æFc TextEdit.h
  84454. æT Function
  84455. æTN A812
  84456. æD pascal void TEPinScroll(short dh,short dv,TEHandle hTE)
  84457.     = 0xA812; 
  84458. æDT TEPinScroll((short) dh,(short) dv,(TEHandle) hTE);
  84459. æMM
  84460. æRI IV-57
  84461. æC 
  84462. [Volume IV addition]
  84463.  
  84464. TEPinScroll is similar to TEScroll except that it stops scrolling when the last line
  84465. scrolls into the view rectangle.
  84466.  
  84467. æKY TEAutoView
  84468. æFc TextEdit.h
  84469. æT Function
  84470. æTN A813
  84471. æD pascal void TEAutoView(Boolean fAuto,TEHandle hTE)
  84472.     = 0xA813; 
  84473. æDT TEAutoView((Boolean) fAuto,(TEHandle) hTE);
  84474. æMM
  84475. æRI IV-57
  84476. æC  
  84477. [Volume IV addition]
  84478.  
  84479. TEAutoView enables and disables automatic scrolling of text in the edit record specified
  84480. by hTe. If the auto parameter is FALSE, automatic scrolling is disabled and calling
  84481. TESelView has no effect.
  84482.  
  84483. æKY TEScrapHandle
  84484. æFc TextEdit.h
  84485. æT Function
  84486. æD pascal Handle TEScrapHandle(void)
  84487.     = {0x2EB8,0x0AB4}; 
  84488. æDT Handle myVariable = TEScrapHandle()(void);
  84489. æRI I-389
  84490. æC  
  84491. [Not in ROM]
  84492.  
  84493. TEScrapHandle returns a handle to the TextEdit scrap.
  84494.  
  84495. Assembly-language note:  The global variable TEScrpHandle contains a handle
  84496.                          to the TextEdit scrap.
  84497.  
  84498. æKY TECalText
  84499. æFc TextEdit.h
  84500. æT Function
  84501. æTN A9D0
  84502. æD pascal void TECalText(TEHandle hTE)
  84503.     = 0xA9D0; 
  84504. æDT TECalText((TEHandle) hTE);
  84505. æMM
  84506. æRI I-390
  84507. æC 
  84508. TECalText recalculates the beginnings of all lines of text in the edit record specified
  84509. by hTE, updating elements of the lineStarts array. Call TECalText if you’ve changed
  84510. the destination rectangle, the hText field, or any other field that affects the
  84511. number of characters per line.
  84512.  
  84513. Note:  There are two ways to specify text to be edited. The easiest method
  84514.        is to use TESetText, which takes an existing edit record, creates a
  84515.        copy of the specified text, and stores a handle to the copy in the
  84516.        edit record. You can instead directly change the hText field of the
  84517.        edit record, and then call TECalText to recalculate the lineStarts
  84518.        array to match the new text. If you have a lot of text, you can use
  84519.        the latter method to save space.
  84520.  
  84521. Assembly-language note:  The global variable TERecal contains the address
  84522.                          of the routine called by TECalText to recalculate
  84523.                          the line starts and set the first and last characters
  84524.                          that need to be redrawn. The registers contain the
  84525.                          following:
  84526.  
  84527.                            On entry  A3:  pointer to the locked edit record
  84528.                                      D7:  change in the length of the
  84529.                                           record (word)
  84530.                            On exit   D2:  line start of the line containing
  84531.                                           the first character to be
  84532.                                           redrawn (word)
  84533.                                      D3:  position of first character to be
  84534.                                           redrawn (word)
  84535.                                      D4:  position of last character to be
  84536.                                           redrawn (word)
  84537.  
  84538. Assembly-language note:  The global variable TEDoText contains the address
  84539.                          of a multi-purpose text editing routine that advanced
  84540.                          programmers may find useful. It lets you display,
  84541.                          highlight, and hit-test characters, and position the
  84542.                          pen to draw the caret. “Hit-test” means decide where
  84543.                          to place the insertion point when the user clicks the
  84544.                          mouse button; the point selected with the mouse is in
  84545.                          the teSelPoint field. The registers contain the
  84546.                          following:
  84547.  
  84548.                            On entry  A3:  pointer to the locked edit record
  84549.                                      D3:  position of first character to be
  84550.                                           redrawn (word)
  84551.                                      D4:  position of last character to be
  84552.                                           redrawn (word)
  84553.                                      D7:  (word)  0 to hit-test a character
  84554.                                                   1 to highlight the selection
  84555.                                                     range
  84556.                                                  –1 to display the text
  84557.                                                  –2 to position the pen to
  84558.                                                     draw the caret
  84559.                            On exit   A0:  pointer to current grafPort
  84560.                                      D0:  if hit-testing, character position
  84561.                                           or –1 for none (word)
  84562.  
  84563. æKY TEGetOffset
  84564. æFc TextEdit.h
  84565. æT Function
  84566. æTN A83C
  84567. æD pascal short TEGetOffset(Point pt,TEHandle hTE)
  84568.     = 0xA83C; 
  84569. æDT short myVariable = TEGetOffset((Point) pt,(TEHandle) hTE);
  84570. æMM
  84571. æRI V-268
  84572. æC 
  84573. [Styled TextEdit]
  84574.  
  84575. The TEGetOffset routine finds the character offset in an edit record’s text corresponding
  84576. to the given point.  TEGetOffset works for both old-style and
  84577. new-style edit records.
  84578.  
  84579. æKY TEGetPoint
  84580. æFc TextEdit.h
  84581. æT Function
  84582. æTN $A83D
  84583. æD pascal struct Point TEGetPoint(short offset,TEHandle hTE)
  84584.     = {0x3F3C,0x0008,0xA83D}; 
  84585. æDT struct Point myVariable = TEGetPoint((short) offset,(TEHandle) hTE);
  84586. æMM
  84587. æRI V-269, VI
  84588. æC 
  84589. With this version of TextEdit, the TEGetPoint routine returns a valid result
  84590. when there is no text in TERecord. The point returned is based on the values in
  84591. the record’s destination rectangle. The line height, taken either from the
  84592. lineHeight field for an unstyled TERecord or from the LHElement array for a
  84593. styled TERecord, is also used to determine the vertical component. Both the line
  84594. and system justifications (teJust and TESysJust) are used to determine the
  84595. horizontal component.
  84596.  
  84597. In the case of the offset equal to a line end (which is also the line start of
  84598. the next line), TEGetPoint returns a point corresponding to the line start of
  84599. the next line. For example, as shown in Figure 14-14, if the offset 3 is passed
  84600. to TEGetPoint, the point returned corresponds to the offset 3 before the
  84601. character d on the second line. In the case of a mixed-directional line, the
  84602. primary caret position (the one corresponding to the line direction) is 
  84603. returned. See “Working with Mixed-Directional Text” earlier in this chapter for
  84604. details on primary caret position in a line containing bidirectional text.
  84605.  
  84606. ø 14.14  Character offset at line break.
  84607.  
  84608. æKY TEClick
  84609. æFc TextEdit.h
  84610. æT Function
  84611. æTN A9D4
  84612. æD pascal void TEClick(Point pt,Boolean fExtend,TEHandle h)
  84613.     = 0xA9D4; 
  84614. æDT TEClick((Point) pt,(Boolean) fExtend,(TEHandle) h);
  84615. æMM
  84616. æRI I-384, P-118, 182
  84617. æC 
  84618. TEClick controls the placement and highlighting of the selection range as determined
  84619. by mouse events. Call TEClick whenever a mouse-down event occurs in the view rectangle
  84620. of the edit record specified by hTE, and the window associated with that edit record
  84621. is active. TEClick keeps control until the mouse button is released. Pt is the mouse
  84622. location (in local coordinates) at the time the button was pressed, obtainable from
  84623. the event record.
  84624.  
  84625. Note:  Use the QuickDraw procedure GlobalToLocal to convert the global
  84626.        coordinates of the mouse location given in the event record to
  84627.        the local coordinate system for pt.
  84628.  
  84629. Pass TRUE for the extend parameter if the Event Manager indicates that the Shift key
  84630. was held down at the time of the click (to extend the selection).
  84631.  
  84632. TEClick unhighlights the old selection range unless the selection range is being
  84633. extended. If the mouse moves, meaning that a drag is occurring, TEClick expands or
  84634. shortens the selection range accordingly. In the case of a double-click, the word
  84635. under the cursor becomes the selection range; dragging expands or shortens the selection
  84636. a word at a time.
  84637.  
  84638. æKY TEStylNew
  84639. æFc TextEdit.h
  84640. æT Function
  84641. æTN A83E
  84642. æD pascal TEHandle TEStylNew(const Rect *destRect,const Rect *viewRect)
  84643.     = 0xA83E; 
  84644. æDT TEHandle myVariable = TEStylNew((const Rect *) destRect,(const Rect *) viewRect);
  84645. æMM
  84646. æRT 131
  84647. æRI V-268, N131-2
  84648. æC 
  84649. [Styled TextEdit]
  84650.  
  84651. The TEStylNew routine creates a new-style edit record with associated style information.
  84652. It initializes the new record’s txSize, lineHeight, and fontAscent fields to –1;
  84653. allocates a style record and stores a handle to it in the txFont and txFace fields.
  84654.  
  84655. æKY SetStylHandle
  84656. æFc TextEdit.h
  84657. æT Function
  84658. æTN $A83D
  84659. æD pascal void SetStylHandle(TEStyleHandle theHandle,TEHandle hTE)
  84660.     = {0x3F3C,0x0005,0xA83D}; 
  84661. æDT SetStylHandle((TEStyleHandle) theHandle,(TEHandle) hTE);
  84662. æMM
  84663. æRI V-268
  84664. æC 
  84665. [Styled TextEdit]
  84666.  
  84667. The SetStylHandle procedure sets an edit record’s style handle, stored in the txFont
  84668. and txFace fields.  SetStylHandle has no effect on an old-style edit record.  Applications
  84669. should always use SetStylHandle rather than manipulating the fields of the edit
  84670. record directly.
  84671.  
  84672. æKY GetStylHandle
  84673. æFc TextEdit.h
  84674. æT Function
  84675. æTN $A83D
  84676. æD pascal TEStyleHandle GetStylHandle(TEHandle hTE)
  84677.     = {0x3F3C,0x0004,0xA83D}; 
  84678. æDT TEStyleHandle myVariable = GetStylHandle((TEHandle) hTE);
  84679. æMM
  84680. æRT 207
  84681. æRI V-268
  84682. æC 
  84683. [Styled TextEdit]
  84684.  
  84685. The GetStylHandle function gets an edit record’s style handle, stored in the txFont
  84686. and txFace fields. GetStylHandle returns NIL when used with an old-style edit record.
  84687. Applications should always use this function rather than manipulating the fields of
  84688. the edit record directly.
  84689.  
  84690. Note:  See Macintosh Technical Note #207 for information on TEContinuousStyle
  84691.        and TENumStyles.
  84692.  
  84693. •••Refer to Technical Note #207:•••
  84694.  
  84695. æKY TEGetStyle
  84696. æFc TextEdit.h
  84697. æT Function
  84698. æTN $A83D
  84699. æD pascal void TEGetStyle(short offset,TextStyle *theStyle,short *lineHeight,
  84700.     short *fontAscent,TEHandle hTE)
  84701.     = {0x3F3C,0x0003,0xA83D}; 
  84702. æDT TEGetStyle((short) offset,(TextStyle *) theStyle,(short *) lineHeight,(
  84703.     short) * fontAscent,(TEHandle) hTE);
  84704. æMM
  84705. æRI V-269
  84706. æC 
  84707. [Styled TextEdit]
  84708.  
  84709. The TEGetStyle procedure returns the style information, including line height and
  84710. font ascent, associated with a given character in an edit record’s text.  For an
  84711. old-style edit record, it returns the record’s global text characteristics.
  84712.  
  84713. æKY TEStylPaste
  84714. æFc TextEdit.h
  84715. æT Function
  84716. æTN $A83D
  84717. æD pascal void TEStylPaste(TEHandle hTE)
  84718.     = {0x3F3C,0x0000,0xA83D}; 
  84719. æDT TEStylPaste((TEHandle) hTE);
  84720. æMM
  84721. æRI V-269
  84722. æC 
  84723. [Styled TextEdit]
  84724.  
  84725. The TEStylPaste procedure pastes text from the desk scrap into the edit
  84726. record’s text at the current insertion point or replaces the current selection.  The
  84727. text is styled according to the style information found in the desk scrap; if there
  84728. is none, it is given the same style as the first character of the replaced selection
  84729. (or that of the preceding character if the selection is an insertion point).  In an
  84730. old-style edit record, just the text is pasted without its accompanying style.
  84731.  
  84732. æKY TESetStyle
  84733. æFc TextEdit.h
  84734. æT Function
  84735. æTN $A83D
  84736. æD pascal void TESetStyle(short mode,const TextStyle *newStyle,Boolean redraw,
  84737.     TEHandle hTE)
  84738.     = {0x3F3C,0x0001,0xA83D}; 
  84739. æDT TESetStyle((short) mode,(const TextStyle *) newStyle,(Boolean) redraw,()
  84740.     TEHandle hTE);
  84741. æMM
  84742. æRT 131, 207
  84743. æRI V-269, N131-1, VI
  84744. æC 
  84745. TESetStyle was enhanced in system software version 6.0 to accept an additional
  84746. mode, doToggle (= 32). For details on TESetStyle, see the “TextEdit” chapter of
  84747. Inside Macintosh, Volume V. When doToggle is specified along with doFace,
  84748. TESetStyle operates as follows:  If a style specified in the given TextStyle
  84749. parameter exists across the entire selected range, that style is removed (turned
  84750. off). Otherwise, all of the selected text is set to include that style. When a
  84751. particular style is set for an entire selection range, that style is said to be
  84752. continuous over the selection.
  84753.  
  84754. For example, if the text  as shown in Figure 14-15, is the current selection,
  84755. then the bold style is continuous over the selection range and the italic style
  84756. is not.
  84757.  
  84758. ø 14.15  Initial selection before TESetStyle is called
  84759.  
  84760. If you call TESetStyle with a mode of doFace + doToggle and a TextStyle tsFace
  84761. field of bold, the resulting selection is as shown in Figure 14-16.
  84762.  
  84763. ø 14.16  TESetStyle called to toggle with a bold style
  84764.  
  84765. On the other hand, if you call TESetStyle with a mode of doFace + doToggle and a
  84766. TextStyle tsFace field of italic, the resulting selection is shown in Figure 
  84767. 14-17.
  84768.  
  84769. ø 14.17  TESetStyle called to toggle with an italic style
  84770. If the TESetStyle redraw parameter is False, TextEdit does not recalculate line
  84771. breaks, line heights, and line ascents. Therefore, when a routine that uses any
  84772. of this information such as TEGetHeight (which returns a total height between
  84773. two specified lines) is called, it does not reflect the new style information
  84774. set with this procedure. Instead, the routine uses the information set before
  84775. TESetStyle was called. To update this information, you must call the TECalText
  84776. routine. A simpler way to be certain that current information is always
  84777. reflected when drawing is to call the TESetStyle routine with the redraw
  84778. parameter set to True.
  84779.  
  84780. Note:  TEReplace also has a redraw with the same parameters specified above.  
  84781.  
  84782. æKY TEReplaceStyle
  84783. æFc TextEdit.h
  84784. æT Function
  84785. æTN $A83D
  84786. æD pascal void TEReplaceStyle(short mode,const TextStyle *oldStyle,const TextStyle *newStyle,
  84787.     Boolean redraw,TEHandle hTE)
  84788.     = {0x3F3C,0x0002,0xA83D}; 
  84789. æDT TEReplaceStyle((short) mode,(const TextStyle *) oldStyle,(const TextStyle *) newStyle,()
  84790.     Boolean redraw,(TEHandle) hTE);
  84791. æMM
  84792. æRI V-270
  84793. æC 
  84794. [Styled TextEdit]
  84795.  
  84796. The TEReplaceStyle procedure replaces the style specified by oldStyle with that given
  84797. by newStyle within the current selection.  (It has no effect on an old-style edit
  84798. record.)  The mode parameter takes the same values as TESetStyle
  84799. (above), except that addSize has no meaning here.  All styles for which the combination
  84800. of attributes designated by mode have the values given by oldStyle are changed to
  84801. have the corresponding values from newStyle instead.  Style changes are made directly
  84802. to the style-table elements within the table itself.  If mode = doAll, newStyle
  84803. simply replaces oldStyle outright.
  84804.  
  84805. æKY GetStylScrap
  84806. æFc TextEdit.h
  84807. æT Function
  84808. æTN $A83D
  84809. æD pascal StScrpHandle GetStylScrap(TEHandle hTE)
  84810.     = {0x3F3C,0x0006,0xA83D}; 
  84811. æDT StScrpHandle myVariable = GetStylScrap((TEHandle) hTE);
  84812. æMM
  84813. æRT 207
  84814. æRI V-268
  84815. æC 
  84816. [Styled TextEdit]
  84817.  
  84818. The GetStylScrap routine allocates a block of type StScrpRec and copies the style
  84819. information associated with the current selection into it. This is the same as TECopy,
  84820. except that no action is performed on the text, and the handle to the 'styl' scrap is
  84821. output in this case. Unlike TECopy, the StScrpRec is not copied to the desk scrap.
  84822.  
  84823. GetStylScrap will return a NIL value if called with an old style TEHandle, or if the
  84824. selection is NIL (stylStart equals stylEnd).
  84825.  
  84826. Note:  See Macintosh Technical Note #207 for information on SetStylScrap.
  84827.  
  84828. •••Refer to Technical Note #207:•••
  84829.  
  84830. æKY TEStylInsert
  84831. æFc TextEdit.h
  84832. æT Function
  84833. æTN $A83D
  84834. æD pascal void TEStylInsert(Ptr text,long length,StScrpHandle hST,TEHandle hTE)
  84835.     = {0x3F3C,0x0007,0xA83D}; 
  84836. æDT TEStylInsert((Ptr) text,(long) length,(StScrpHandle) hST,(TEHandle) hTE);
  84837. æMM
  84838. æRT 131
  84839. æRI V-268, N131-1
  84840. æC 
  84841. [Styled TextEdit]
  84842.  
  84843. The TEStylInsert procedure takes the specified text and inserts it just before the
  84844. selection range into the text indicated by hTE, redrawing the text as necessary. If
  84845. hST is not NIL and hTE is a TextEdit record created using TEStylNew, the style information
  84846. indicated by hST will also be inserted to correspond with the inserted text. When hST
  84847. is NIL and/or hTE has not been created using TEStylNew, there is no difference between
  84848. this procedure and TEInsert. TEStylInsert does not affect either the current selection
  84849. range or the scrap.
  84850.  
  84851. æKY TEGetHeight
  84852. æFc TextEdit.h
  84853. æT Function
  84854. æTN $A83D
  84855. æD pascal long TEGetHeight(long endLine,long startLine,TEHandle hTE)
  84856.     = {0x3F3C,0x0009,0xA83D}; 
  84857. æDT long myVariable = TEGetHeight((long) endLine,(long) startLine,(TEHandle) hTE);
  84858. æMM
  84859. æRI V-269, N131-2
  84860. æC 
  84861. [Styled TextEdit]
  84862.  
  84863. The TEGetHeight routine returns the total height of all the lines in the text between
  84864. and including startLine and endLine. TEGetHeight works for both old- and new-style
  84865. edit records.
  84866.  
  84867. æKY TEContinuousStyle
  84868. æFc TextEdit.h
  84869. æT Function
  84870. æTN $A83D
  84871. æD pascal Boolean TEContinuousStyle(short *mode,TextStyle *aStyle,TEHandle hTE)
  84872.     = {0x3F3C,0x000A,0xA83D}; 
  84873. æDT Boolean myVariable = TEContinuousStyle((short *) mode,(TextStyle *) aStyle,(TEHandle) hTE);
  84874. æRT 207
  84875. æC 
  84876. TEContinuousStyle, a new routine in system software version 6.0, gives you
  84877. information about the attributes of the current selection. The mode parameter,
  84878. which takes the same values as in TESetStyle, specifies which attributes should
  84879. be checked. For details, refer to Inside Macintosh, Volume V. When
  84880. TEContinuousStyle returns, the mode parameter indicates which of the checked
  84881. attributes is continuous over the selection range and the aStyle parameter
  84882. reflects the continuous attributes.
  84883.  
  84884. TEContinuousStyle returns TRUE if all of the attributes to be checked are
  84885. continuous and FALSE if they are not. In other words, if the mode parameter is
  84886. the same before and after the call, then TEContinuousStyle returns TRUE.
  84887.  
  84888. This code sample illustrates how TEContinuousStyle is useful for marking the
  84889. style menu items based on the current selection.
  84890.  
  84891. mode := doFace;
  84892. IF TEContinuousStyle(mode, aStyle, myTE) THEN BEGIN
  84893. { There is at least one face that is continuous over the}
  84894. { selection. Note that it might be plain, which is actually}
  84895. { the absence of all styles. }
  84896.        CheckItem(styleMenu, plainItem, aStyle.tsFace = []);
  84897.        CheckItem(styleMenu, boldItem, bold IN aStyle.tsFace);
  84898.        CheckItem(styleMenu, italicItem, italic IN aStyle.tsFace);
  84899.   {...etc.}
  84900. END ELSE BEGIN
  84901. { No text face is common to the entire selection. }
  84902.       CheckItem(styleMenu, plainItem, FALSE);
  84903.       CheckItem(styleMenu, boldItem, FALSE);
  84904.       CheckItem(styleMenu, italicItem, FALSE);
  84905.   {...etc.}
  84906. END;
  84907.  
  84908. You can also use TEContinuousStyle to determine the actual values for those
  84909. attributes that are continuous for the selection. Note that a field in the
  84910. TextStyle record is only valid if the corresponding bit is set in the mode
  84911. variable; otherwise, the field contains invalid information. The following code
  84912. sample illustrates how you might use TEContinuousStyle to determine the font,
  84913. face, size, and color of the current selection:
  84914.  
  84915.   mode := doFont + doFace + doSize + doColor;
  84916.   continuous := TEContinuousStyle(mode, aStyle, myTE);
  84917.   IF BitAnd(mode, doFont) <> 0 THEN
  84918.     { Font for selection = aStyle.tsFont.} 
  84919.  
  84920.   ELSE
  84921.     { More than one font in selection. };
  84922.  
  84923.   IF BitAnd(mode, doFace) <> 0 THEN
  84924.     { aStyle.tsFace contains the text faces (or plain) that are
  84925.       common to the selection. }
  84926.  
  84927.   ELSE
  84928.     { No text face is common to the entire selection. };
  84929.  
  84930.   IF BitAnd(mode, doSize) <> 0 THEN
  84931.     { Size for selection = aStyle.tsSize. }
  84932.  
  84933.   ELSE
  84934.     { More than one size in selection. };
  84935.  
  84936.   IF BitAnd(mode, doColor) <> 0 THEN
  84937.     { Color for selection = aStyle.tsColor. }
  84938.  
  84939.   ELSE
  84940.     { More than one color in selection. };
  84941.  
  84942. When TEContinuousStyle returns a mode that contains doFace, and an aStyle.tsFace
  84943. field that contains [bold, italic], it means that the selected text is all bold
  84944. and all italic, but may contain other text faces as well. None of the other
  84945. faces applies to all of the selected text, or they would have been included in
  84946. the tsFace field.  But if the tsFace field is the empty set, then all of the
  84947. selected text is plain.
  84948.  
  84949. If the current selection range is an insertion point, TEContinuousStyle returns
  84950. the style information for the next character to be typed. TEContinuousStyle
  84951. always returns TRUE in this case, and each field of the TextStyle record will be
  84952. set if the corresponding bit in the mode parameter was set. If hTE is a handle
  84953. to an old style record, TEContinuousStyle returns the simple style information
  84954. of the entire record.
  84955.  
  84956.  
  84957. æKY SetStylScrap
  84958. æFc TextEdit.h
  84959. æT Function
  84960. æTN $A83D
  84961. æD pascal void SetStylScrap(long rangeStart,long rangeEnd,StScrpHandle newStyles,
  84962.     Boolean redraw,TEHandle hTE)
  84963.     = {0x3F3C,0x000B,0xA83D}; 
  84964. æDT SetStylScrap((long) rangeStart,(long) rangeEnd,(StScrpHandle) newStyles,()
  84965.     Boolean redraw,(TEHandle) hTE);
  84966. æRT 207
  84967. æC 
  84968. SetStylScrap performs the opposite function of the GetStylScrap function and was
  84969. new in system software version 6.0. It takes newStyles, a handle to a style
  84970. scrap record, and sets its style information into the StScrpRec record for a
  84971. range of text specified by rangeStart and rangeEnd. If newStyles is NIL or hTE
  84972. is a handle to an old style TERecord, SetStylScrap does nothing.
  84973.  
  84974. If redraw is TRUE, the text is redrawn to reflect this new style information,
  84975. and line breaks, line heights, and line ascents are recalculated. Otherwise,
  84976. this new information is not reflected in the view rectangle until a TEUpdate is
  84977. called. Regardless of whether or not the text is redrawn, the current selection
  84978. range is not changed. So, if characters are highlighted before SetStylScrap is
  84979. called, they remain highlighted after it is called. They also reflect the new
  84980. style information if redraw was TRUE, and they were within the range of text
  84981. specified.
  84982.  
  84983. Each element in the style scrap record contains a ScrpStartChar field which is
  84984. the offset to the start of the element’s style. As with the styleRun array the
  84985. ScrpStartChars define the boundaries for the scrap’s style runs. SetStylScrap
  84986. applies the first element’s style to the characters from rangeStart up to the
  84987. ScrpStartChar field of the next element.
  84988.  
  84989. SetStylScrap terminates without error if it prematurely reaches the end of the
  84990. range or if there are not enough scrap style elements to cover the whole range.
  84991. In the latter case, it applies the last style in the scrap record to the
  84992. remainder of the range.
  84993.  
  84994. æKY TECustomHook
  84995. æFc TextEdit.h
  84996. æT Function
  84997. æTN $A83D
  84998. æD pascal void TECustomHook(TEIntHook which,ProcPtr *addr,TEHandle hTE)
  84999.     = {0x3F3C,0x000C,0xA83D}; 
  85000. æDT TECustomHook((TEIntHook) which,(ProcPtr *) addr,(TEHandle) hTE);
  85001. æRT 207
  85002. æC 
  85003. The TECustomHook procedure lets applications customize the functions of TextEdit
  85004. by setting the TextEdit hooks. The which parameter specifies which hook to
  85005. replace, and is of type TEIntHook. 
  85006.  
  85007. TYPE
  85008.     TEIntHook = Integer;
  85009.  
  85010. The values for the which parameter are
  85011.  
  85012. CONST {Selectors for TECustomHook}
  85013.        intEOLHook      = 0;
  85014.        intDrawHook     = 1;
  85015.        intWidthHook    = 2;
  85016.        intHitTestHook  = 3;
  85017.        intNWidthHook   = 6;
  85018.  
  85019. When TECustomHook returns, the addr parameter contains the address of the
  85020. previous hook specified by which.  This address is returned so that hooks can be
  85021. daisy-chained. The new hook, nTEWidthHook, is described below in the Measuring
  85022. the Width of Line Components” section.
  85023.  
  85024. Two fields of TERecord, recalBack and recalLines, combine to hold a handle to
  85025. TEDispatchRec, which contains a list of TextEdit hooks. Each TERecord has its
  85026. own set of such routines to provide for maximum flexibility. You should always
  85027. use the TECustomHook procedure to change these hooks instead of modifying the
  85028. edit record directly.
  85029.  
  85030. †  Warning:  Do not duplicate a TERecord. If you do, a duplicate handle to the
  85031. initial TEDispatchRec is stored in recalBack and recalLines in your copy of the
  85032. record. When one of the TextEdit records is disposed, the handle stored in the
  85033. copy becomes invalid, and TextEdit crashes. Ê 
  85034.  
  85035. TEEOLHook, TEWidthHook, nTEWidthHook, TEDrawHook, and TEHitTestHook are offsets
  85036. into TEDispatchRec and are described in the next sections. 
  85037.  
  85038. When you replace these hooks, note that all registers except those specified as
  85039. containing return values must be preserved. Registers A3 and A4 contain a
  85040. pointer and a handle to the TextEdit record respectively. You can obtain line
  85041. start positions from the lineStarts array in the edit record. A5 is always valid
  85042. and moves memory.
  85043.  
  85044. Note:  None of these TextEdit hooks is called from TextBox.
  85045.  
  85046. æKY TENumStyles
  85047. æFc TextEdit.h
  85048. æT Function
  85049. æTN $A83D
  85050. æD pascal long TENumStyles(long rangeStart,long rangeEnd,TEHandle hTE)
  85051.     = {0x3F3C,0x000D,0xA83D}; 
  85052. æDT long myVariable = TENumStyles((long) rangeStart,(long) rangeEnd,(TEHandle) hTE);
  85053. æRT 207
  85054. æC 
  85055. The TENumStyles function returns the number of style changes contained in the
  85056. given range, counting one for the start of the range. Note that this does not
  85057. necessarily represent the number of unique styles for the range because some
  85058. styles may be repeated. For unstyled TextEdit records, TENumStyles always
  85059. returns 1.
  85060.  
  85061. You can use TENumStyles to calculate the amount of memory that would be required
  85062. if TECut or TECopy were called. Since the style scrap record is linear in 
  85063. nature, with one element for each style change, you can multiply the result that
  85064. TENumStyles returns by SizeOf(ScrpSTElement) and add 2 to get the amount of
  85065. memory needed.
  85066.  
  85067. æKY TEFeatureFlag
  85068. æFc TextEdit.h
  85069. æT Function
  85070. æTN A83D
  85071. æD pascal short TEFeatureFlag(short feature,short action,TEHandle hTE)
  85072.     = {0x3F3C,0x000E,0xA83D}; 
  85073. æDT short myVariable = TEFeatureFlag((short) feature,(short) action,(TEHandle) hTE);
  85074. æC 
  85075. The TEFeatureFlag function allows you to enable outline highlighting and text
  85076. buffering in your application.  Your application can control these features
  85077. using the TEBitClear and TEBitSet constants for the action parameter. You can
  85078. also test the settings of these feature bits with the TEBitTest constant. 
  85079. The result of TEFeatureFlag is the previous setting of the features bit, either
  85080. TEBitSet or TEBitClear.
  85081.  
  85082. CONST {Constants for feature parameter values}
  85083.        teFTextBuffering  = 1;
  85084.        teFOutlineHilite  = 2;
  85085.  
  85086. CONST {Constants for action parameter values}
  85087.        TEBitClear       = 0;
  85088.        TEBitSet         = 1;
  85089.        TEBitTest        =-1;
  85090.  
  85091. The teFOutlineHilite value specified in the feature parameter of TEFeatureFlag
  85092. lets your application enable outline highlighting. If a highlighted (inverted)
  85093. region exists in a deactivated window, then the highlighted region is outlined 
  85094. (or framed) when the window is in the background, similar to the behavior of MPW
  85095. selections. If the caret is in the window and the window is no longer active,
  85096. the caret then appears dimmed. To do the framing, TextEdit replaces the current
  85097. address in the highHook and caretHook fields of the TERecord data structure and
  85098. then restores the hooks to their previous addresses.
  85099.  
  85100. The teFTextBuffering value specified in the feature parameter of TEFeatureFlag
  85101. allows your application to perform text buffering. Text buffering can be enabled
  85102. for performance improvements, especially with East Asian scripts. TextEdit
  85103. buffers each TEKey input of a graphic character until no more characters are
  85104. being inserted. The entire buffer may then be inserted at one time if any
  85105. TextEdit routine is called other than TEKey for another graphic character. The
  85106. buffer is dumped before this routine is handled.
  85107.  
  85108. This buffer is a global buffer (and differs from TEKey’s double-byte buffer),
  85109. used across all active TextEdit records;. these records may be in a single
  85110. application or in multiple applications each having a TERecord. Exercise care
  85111. when you enable TEFeatureFlag’s text buffering capability in more than one
  85112. active record; otherwise, the bytes that are buffered from one TextEdit record
  85113. may appear in another TextEdit record. You also need to be sure that buffering
  85114. is not turned off in the middle of processing a double-byte character. 
  85115.  
  85116. To guarantee the integrity of your record, it is important that you wait for an
  85117. idle event before you disable buffering or enable buffering in a second TextEdit
  85118. record.
  85119.  
  85120. If text buffering is enabled on a non-Roman script system and the keyboard has
  85121. changed, TextEdit flushes the text of the current script from the buffer before
  85122. buffering characters in the new script.
  85123.  
  85124. Note: If the text buffering feature teFTextBuffering is enabled, your
  85125. application must ensure that TEIdle is called before any pause of more than a
  85126. few ticks—for example, before WaitNextEvent. A possibility of a long delay
  85127. before characters appear on the screen exists—especially in non-Roman systems.
  85128. If you do not call TEIdle, the characters may end up in the TERecord of another
  85129. application.
  85130.  
  85131. æKY TEGetScrapLen
  85132. æFc TextEdit.h
  85133. æT Function
  85134. æD pascal long TEGetScrapLen(void); 
  85135. æDT long myVariable = TEGetScrapLen()(void);
  85136. æRI I-389
  85137. æC 
  85138. [Not in ROM]
  85139.  
  85140. TEGetScrapLen returns the size of the TextEdit scrap in bytes.
  85141.  
  85142. Assembly-language note:  The global variable TEScrpLength contains the size
  85143.                          of the TextEdit scrap in bytes.
  85144.  
  85145. æKY TESetScrapLen
  85146. æFc TextEdit.h
  85147. æT Function
  85148. æD pascal void TESetScrapLen(long length); 
  85149. æDT TESetScrapLen((long) length);
  85150. æRI I-390
  85151. æC 
  85152. [Not in ROM]
  85153.  
  85154. TESetScrapLen sets the size of the TextEdit scrap to the given number of bytes.
  85155.  
  85156. Assembly-language note:  From assembly language, you can set the global
  85157.                          variable TEScrpLength.
  85158.  
  85159. æKY TEFromScrap
  85160. æFc TextEdit.h
  85161. æT Function
  85162. æD pascal OSErr TEFromScrap(void); 
  85163. æDT OSErr myVariable = TEFromScrap()(void);
  85164. æMM
  85165. æRI I-389
  85166. æC  
  85167. »Scrap Handling
  85168.  
  85169. The TEFromScrap and TEToScrap functions return a result code of type OSErr
  85170. (defined as INTEGER in the Operating System Utilities) indicating whether an error
  85171. occurred. If no error occurred, they return the result code
  85172.  
  85173. CONST noErr = 0; {no error}
  85174.  
  85175. Otherwise, they return an Operating System result code indicating an error.
  85176. (See Appendix A for a list of all result codes.)
  85177.  
  85178. [Not in ROM]
  85179.  
  85180. TEFromScrap copies the desk scrap to the TextEdit scrap. If no error occurs, it
  85181. returns the result code noErr; otherwise, it returns an appropriate Operating System
  85182. result code.
  85183.  
  85184. Assembly-language note:  From assembly language, you can store a handle to
  85185.                          the desk scrap in the global variable TEScrpHandle,
  85186.                          and the size of the desk scrap in the global
  85187.                          variable TEScrpLength; you can get these values
  85188.                          with the Scrap Manager function InfoScrap.
  85189.  
  85190. æKY TEToScrap
  85191. æFc TextEdit.h
  85192. æT Function
  85193. æD pascal OSErr TEToScrap(void); 
  85194. æDT OSErr myVariable = TEToScrap()(void);
  85195. æMM
  85196. æRI I-389
  85197. æC 
  85198. »Scrap Handling
  85199.  
  85200. The TEFromScrap and TEToScrap functions return a result code of type OSErr
  85201. (defined as INTEGER in the Operating System Utilities) indicating whether an error
  85202. occurred. If no error occurred, they return the result code
  85203.  
  85204. CONST noErr = 0; {no error}
  85205.  
  85206. Otherwise, they return an Operating System result code indicating an error.
  85207. (See Appendix A for a list of all result codes.)
  85208.  
  85209. [Not in ROM]
  85210.  
  85211. TEToScrap copies the TextEdit scrap to the desk scrap. If no error occurs, it returns
  85212. the result code noErr; otherwise, it returns an appropriate Operating System result
  85213. code.
  85214.  
  85215. Warning:  You must call the Scrap Manager function ZeroScrap to initialize
  85216.           the desk scrap or clear its previous contents before calling
  85217.           TEToScrap.
  85218.  
  85219. Assembly-language note:  From assembly language, you can copy the TextEdit
  85220.                          scrap to the desk scrap by calling the Scrap Manager
  85221.                          function PutScrap; you can get the values you need
  85222.                          from the global variables TEScrpHandle and
  85223.                          TEScrpLength.
  85224.  
  85225. æKY SetClikLoop
  85226. æFc TextEdit.h
  85227. æT Function
  85228. æD pascal void SetClikLoop(ClikLoopProcPtr clikProc,TEHandle hTE); 
  85229. æDT SetClikLoop((ClikLoopProcPtr) clikProc,(TEHandle) hTE);
  85230. æRI I-390
  85231. æC 
  85232. [Not in ROM]
  85233.  
  85234. SetClikLoop installs in the clikLoop field of the specified edit record a special
  85235. routine that calls the click loop routine pointed to by clikProc. The specified click
  85236. loop routine will be called repeatedly as long as the user holds down the mouse
  85237. button within the text, as described above under “The ClikLoop Field” in the “Edit
  85238. Records” section.
  85239.  
  85240. Assembly-language note:  Like SetWordBreak, this procedure isn’t necessary
  85241.                          from assembly language; just set the field of the
  85242.                          edit record to point to your click loop routine.
  85243.  
  85244. Note:  See Macintosh Technical Note #207 for information on TECustomHook,
  85245.        which provides TEEOLHook, TEWidthHook, TEDrawHook, and TEHitTestHook.
  85246.  
  85247. •••Refer to Technical Note #207:•••
  85248.  
  85249. æKY SetWordBreak
  85250. æFc TextEdit.h
  85251. æT Function
  85252. æD pascal void SetWordBreak(WordBreakProcPtr wBrkProc,TEHandle hTE); 
  85253. æDT SetWordBreak((WordBreakProcPtr) wBrkProc,(TEHandle) hTE);
  85254. æRI I-390
  85255. æC 
  85256. [Not in ROM]
  85257.  
  85258. SetWordBreak installs in the wordBreak field of the specified edit record a special
  85259. routine that calls the word break routine pointed to by wBrkProc. The specified word
  85260. break routine will be called instead of TextEdit’s default routine, as described
  85261. under “The WordBreak Field” in the “Edit Records” section.
  85262.  
  85263. Assembly-language note:  From assembly language you don’t need this
  85264.                          procedure; just set the field of the edit record
  85265.                          to point to your word break routine.
  85266.  
  85267. æKY teclick
  85268. æFc TextEdit.h
  85269. æT Function
  85270. æD void teclick(Point *pt,Boolean fExtend,TEHandle h); 
  85271. æDT teclick((Point *) pt,(Boolean) fExtend,(TEHandle) h);
  85272. æMM
  85273. æRI I-384, P-118, 182
  85274. æC 
  85275. TEClick controls the placement and highlighting of the selection range as determined
  85276. by mouse events. Call TEClick whenever a mouse-down event occurs in the view rectangle
  85277. of the edit record specified by hTE, and the window associated with that edit record
  85278. is active. TEClick keeps control until the mouse button is released. Pt is the mouse
  85279. location (in local coordinates) at the time the button was pressed, obtainable from
  85280. the event record.
  85281.  
  85282. Note:  Use the QuickDraw procedure GlobalToLocal to convert the global
  85283.        coordinates of the mouse location given in the event record to
  85284.        the local coordinate system for pt.
  85285.  
  85286. Pass TRUE for the extend parameter if the Event Manager indicates that the Shift key
  85287. was held down at the time of the click (to extend the selection).
  85288.  
  85289. TEClick unhighlights the old selection range unless the selection range is being
  85290. extended. If the mouse moves, meaning that a drag is occurring, TEClick expands or
  85291. shortens the selection range accordingly. In the case of a double-click, the word
  85292. under the cursor becomes the selection range; dragging expands or shortens the selection
  85293. a word at a time.
  85294.  
  85295.  
  85296. æKY Time.h
  85297. æFc Time.h
  85298. æKL asctime
  85299. clock
  85300. ctime
  85301. difftime
  85302. gmtime
  85303. localtime
  85304. mktime
  85305. strftime
  85306. time
  85307.  
  85308. æKY asctime
  85309. ctime
  85310. gmtime
  85311. localtime
  85312. strftime
  85313. æFc Time.h
  85314. æC                            Synopsis
  85315.  
  85316. #include <Time.h>
  85317. char *asctime (const struct tm *timeptr);
  85318. char *ctime (const time_t *timer);
  85319. struct tm *gmtime (const time_t *timer);
  85320. struct tm *localtime (const time_t *timer);
  85321. size_t strftime (char *s, size_t maxsize, const char *format,
  85322.                      const struct tm *timeptr);
  85323.  
  85324.                            Description
  85325.  
  85326. The asctime; function converts the local time contained in the 
  85327. tm structure into a string of the form
  85328. Mo   Sep 12  08:08:08    1988\n\0
  85329.  
  85330. The localtime; function coverts the calendar time in seconds 
  85331. to local time contained in struct tm.
  85332.  
  85333. The ctime; function converts the calendar time returned by 
  85334. timer into a string expressing the local time. This is the same as 
  85335. calling asctime (localtime(timeptr))
  85336.  
  85337. The gmtime; function converts the calendar time returned by 
  85338. timer into Coordinated Universal Time. It returns a NULL.
  85339.  
  85340. The strftime; function includes a number of format 
  85341. characters used to place characters into array s. The strftime 
  85342. format string can consist of zero or more conversion specifiers 
  85343. and ordinary multibyte characters. Each conversion specifier 
  85344. includes a % preceding one of the characters listed below. All 
  85345. ordinary multibyte characters (including the terminating \0) are 
  85346. copied into array s unchanged. If overlapping objects are 
  85347. copied, the behavior is undefined. A maximum of maxsize 
  85348. characters can be placed into array s. Each conversion 
  85349. specifier is replaced by one of the characters in the following 
  85350. list. The program’s locale and the values contained in timeptr 
  85351. will determine which characters to use.
  85352.  
  85353. Specifier    Replaced by
  85354.  
  85355. %a   the abbreviated weekday name for the locale
  85356. %A   the full weekday name for the locale
  85357. %b   the abbreviated month name for the locale
  85358. %B   the full month name for the locale
  85359. %c   the appropriate date and time representation for the 
  85360.      locale
  85361. %d   the day of the month as a decimal number (01-31)
  85362. %H   the hour (24-hour clock) as a decimal number (00-23)
  85363. %I   the hour (12-hour clock) as a decimal number (01-12)
  85364. %j   the day of the year as a decimal number (001-366)
  85365. %m   the month as a decimal number (01-12)
  85366. %M   the minute as a decimal number (00-59)
  85367. %p   the equivalent of either AM or PM for the locale
  85368. %S   the second as a decimal number (00-60)
  85369. %U   the week number of the year (Sunday as the first day 
  85370.      of the week) as a decimal number (00-53)
  85371. %w   the weekday as a decimal number (0-6, Sunday is 0)
  85372. %W   the week number of the year (Monday as the first day 
  85373.      of the week) as a decimal number (00-53)
  85374. %x   the appropriate date representation for the locale
  85375. %X   the appropriate time representation for the locale
  85376. %y   the year without century as a decimal number (00-99)
  85377. %Y   the year with century as a decimal number
  85378. %Z   the time zone name, or no characters if time zone is not 
  85379.      determinable
  85380. %%   the percent sign (%)
  85381. For any conversion specifier not listed above, the behavior is 
  85382. undefined.  
  85383.  
  85384. æKY clock
  85385. difftime
  85386. mktime
  85387. time
  85388. æFc Time.h
  85389. æC The Standard C library provides functions for manipulating and 
  85390. converting the date and time: finding the time, calculating the 
  85391. difference between times, converting to and from string format, 
  85392. and converting between calendar time, local time, and 
  85393. Coordinated Universal Time. 
  85394.  
  85395.                            Synopsis
  85396.  
  85397. #include <Time.h>
  85398. #define  NULL 0
  85399. #define size_t unsigned int
  85400. #define CLK_TCK 60
  85401. /* arithmetic types representing times */
  85402. typedef long int clock_t;
  85403. typedef unsigned long int time_t;
  85404. clock_t clock (void);
  85405. double difftime (time_t time1, time_t time0);
  85406. time_t mktime (struct tm *timeptr);
  85407. time_t time (time_t *timer);
  85408.  
  85409.                            Description
  85410.  
  85411. The struct tm holds the components of a calendar time, broken 
  85412. down as follows.
  85413. Component    Meaning                     Range (min, max)
  85414.  
  85415. int tm_sec;  seconds after the minute    (0, 59)
  85416. int tm_min;  minutes after the hour      (0, 59)
  85417. int tm_hour; hours after midnight        (0, 23)
  85418. int tm_mday; day of the month            (1, 31)
  85419. int tm_mon;  months since January        (0, 11)
  85420. int tm_year; years since 1900    
  85421. int tm_wday; days since Sunday           (0, 6)
  85422. int tm_yday; days since January 1        (0, 365)
  85423. int tm_isdst; Daylight Saving Time flag   
  85424.  
  85425. The tm_isdst component is positive if Daylight Saving Time is in 
  85426. effect; zero if it is not in effect; and negative if it is unknown 
  85427. whether it is in effect.
  85428.  
  85429. The clock; function returns the amount of time since the 
  85430. Macintosh was last booted. It returns –1 if it can’t determine 
  85431. the time.
  85432.  
  85433. The difftime; function returns the difference between two 
  85434. calendar times, expressed in seconds.
  85435.  
  85436. The time; function returns the current calendar time. It 
  85437. returns a –1 if it can’t determine the time.
  85438.  
  85439. The mktime; function calculates times according to the ranges 
  85440. stored within the struct tm. If successful, mktime uses these 
  85441. ranges to convert the submitted local time into the 
  85442. corresponding calendar time. For example, the local time values 
  85443. for tm_year, tm_mon, and tm_mday will return a calendar time as 
  85444. shown below:
  85445. Local time   Calendar time   Comment
  85446.  
  85447. tm_year = 88 89  add 14 to 01/88
  85448. tm_mon  = 14  2  February 
  85449. tm_wday = 13  6  Saturday 
  85450.  
  85451. The final value of tm_mday isn’t calculated until tm_mon and 
  85452. tm_year are determined. If mktime can’t determine the time, it 
  85453. returns a –1. 
  85454.  
  85455.  
  85456. æKY asctimeæ
  85457. æDT 
  85458. char * myVariable = asctime ((const struct tm *)timeptr);
  85459.  
  85460. æKY clockæ
  85461. æDT 
  85462. clock_t myVariable = clock (void);
  85463.  
  85464. æKY ctimeæ
  85465. æDT 
  85466. char * myVariable = ctime ((const time_t *)timer);
  85467.  
  85468.  
  85469. æKY difftimeæ
  85470. æDT 
  85471. double myVariable = difftime ((time_t) time1, (time_t) time0);
  85472.  
  85473. æKY gmtimeæ
  85474. æDT 
  85475. struct tm * myVariable = gmtime ((const time_t *)timer);
  85476.  
  85477. æKY localtimeæ
  85478. æDT 
  85479. struct tm * myVariable = localtime ((const time_t *)timer);
  85480.  
  85481. æKY mktimeæ
  85482. æDT 
  85483. time_t myVariable = mktime ((struct tm *)timeptr);
  85484.  
  85485. æKY strftimeæ
  85486. æDT 
  85487. size_t myVariable = strftime ((char *)s, (size_t) maxsize, (const char *)format,
  85488.                      (const struct tm *)timeptr);
  85489.  
  85490. æKY timeæ
  85491. æDT 
  85492. time_t myVariable = time ((time_t *)timer);
  85493.  
  85494.  
  85495. æKY Timer.h
  85496. æKL InsTime
  85497. InsXTime
  85498. PrimeTime
  85499. RmvTime
  85500.  
  85501. TimerProcPtr
  85502. TMTask
  85503. TMTaskPtr
  85504.  
  85505. æKY TimerProcPtr
  85506. æFc Timer.h
  85507. æT typedef
  85508. æD typedef pascal void (*TimerProcPtr)(void);
  85509. æC 
  85510.  
  85511. æKY TMTask
  85512. TMTaskPtr
  85513. æFc Timer.h
  85514. æT struct
  85515. æD struct TMTask {
  85516.     QElemPtr qLink;
  85517.     short qType;
  85518.     TimerProcPtr tmAddr;
  85519.     long tmCount;
  85520.     long tmWakeUp;
  85521.     long tmReserved;
  85522. };
  85523.  
  85524. typedef struct TMTask TMTask;
  85525. typedef TMTask *TMTaskPtr;
  85526.  
  85527. æC 
  85528. »ABOUT THE TIME MANAGER
  85529. _______________________________________________________________________________
  85530.  
  85531. The Time Manager provides the user with an asynchronous “wakeup” service with
  85532. 1-millisecond accuracy; it can have any number of outstanding wakeup requests. The
  85533. Time Manager is independent of clock speed or interrupts, and should be used in place
  85534. of cycle-counting timing loops.
  85535.  
  85536. An application can add any number of tasks for the Time Manager to schedule. These
  85537. tasks can perform any desired action so long as they don’t make any calls to the
  85538. Memory Manager, directly or indirectly, and don’t depend on handles to unlocked
  85539. blocks being valid. They must preserve all registers other than A0–A3 and D0–D3. If
  85540. they use application globals, they must also ensure that register A5 contains the
  85541. address of the boundary between the application globals and the application parameters;
  85542. for details, see SetCurrentA5 and SetA5 in Macintosh Technical Note #208.
  85543.  
  85544. •••Refer to Technical Note #208:•••
  85545.  
  85546. Note:  To perform periodic actions that do allocate and release memory, you
  85547.        can use the Desk Manager procedure SystemTask.
  85548.  
  85549. Information describing each Time Manager task is contained in the Time Manager queue;
  85550. you need only supply a pointer to the routine to be executed. The Time Manager queue
  85551. is a standard Macintosh queue, as described in the Operating System Utilities chapter.
  85552. Each entry in the Time Manager queue has the following structure:
  85553.  
  85554. TYPE  TMTask = RECORD
  85555.                  qLink:    QElemPtr;  {next queue entry}
  85556.                  qType:    INTEGER;   {queue type}
  85557.                  tmAddr:   ProcPtr;   {pointer to routine}
  85558.                  tmCount:  INTEGER    {reserved}
  85559.                END;
  85560.  
  85561. æKY InsTime
  85562. æFc Timer.h
  85563. æT Function
  85564. æD pascal void InsTime(QElemPtr tmTaskPtr); 
  85565. æDT InsTime((QElemPtr) tmTaskPtr);
  85566. æRI IV-300, VI
  85567. æC 
  85568. You can insert a task into the Time Manager’s queue by calling InsTime or
  85569. InsXTime. After you have queued a task, you must activate it by calling
  85570. PrimeTime. You can remove a task from the queue by calling RmvTime.
  85571.  
  85572. PROCEDURE InsTime (tmTaskPtr: QElemPtr);
  85573.  
  85574. Trap macro  _InsTime
  85575. On entry    A0: address of TMTask record
  85576. On exit     D0: result code
  85577.  
  85578. InsTime adds the Time Manager task specified by tmTaskPtr to the Time Manager
  85579. queue. Your application must fill in the tmAddr field of the task, but should
  85580. not fill in or modify any of the remaining fields. The tmTaskPtr parameter must
  85581. point to an original Time Manager task.
  85582.  
  85583. Result codes
  85584. noErr  0  No error
  85585.  
  85586. æKY InsXTime
  85587. æFc Timer.h
  85588. æT Function
  85589. æD pascal void InsXTime(QElemPtr tmTaskPtr); 
  85590. æDT InsXTime((QElemPtr) tmTaskPtr);
  85591. æRI VI
  85592. æC
  85593. Trap macro  _InsXTime
  85594. On entry    A0: address of TMTask record
  85595. On exit     D0: result code
  85596.  
  85597. InsXTime adds the Time Manager task specified by tmTaskPtr to the Time Manager
  85598. queue. The tmTaskPtr parameter must point to an extended Time Manager task. Your
  85599. application must fill in the tmAddr field of that task.
  85600.  
  85601. Result codes
  85602. noErr  0  No error
  85603.  
  85604.  
  85605.  
  85606. æKY PrimeTime
  85607. æFc Timer.h
  85608. æT Function
  85609. æD pascal void PrimeTime(QElemPtr tmTaskPtr,long count); 
  85610. æDT PrimeTime((QElemPtr) tmTaskPtr,(long) count);
  85611. æRI IV-300, VI
  85612. æC 
  85613. The PrimeTime procedure schedules the routine specified by the tmAddr field of
  85614. tmTaskPtr for execution after the delay specified by the count parameter has
  85615. elapsed.
  85616.  
  85617. PROCEDURE PrimeTime (tmTaskPtr: QElemPtr; count: LongInt);
  85618.  
  85619. Trap macro  _PrimeTime
  85620. On entry    A0: address of TMTask record
  85621.             D0: specified delay time (long)
  85622. On exit     D0: result code
  85623.  
  85624. If count is a positive value, it is interpreted in milliseconds. If count is a
  85625. negative value, it is interpreted in negated microseconds. The queue element
  85626. specified by tmTaskPtr must already be inserted into the queue (by a previous
  85627. call to InsTime or InsXTime) before your application calls the PrimeTime
  85628. procedure. The PrimeTime procedure returns immediately, and the specified
  85629. routine is executed after the specified delay has elapsed. If you call PrimeTime
  85630. with a time delay of 0, the procedure runs as soon as interrupts are enabled.
  85631.  
  85632. Result codes
  85633. noErr  0  No error
  85634.  
  85635. æKY RmvTime
  85636. æFc Timer.h
  85637. æT Function
  85638. æD pascal void RmvTime(QElemPtr tmTaskPtr); 
  85639. æDT RmvTime((QElemPtr) tmTaskPtr);
  85640. æRI IV-300, VI
  85641. æC 
  85642. Trap macro  _RmvTime
  85643. On entry    A0: address of TMTask record
  85644. On exit     D0: result code
  85645.  
  85646. The RmvTime procedure removes the Time Manager task specified by tmTaskPtr from
  85647. the Time Manager queue. In both the revised and extended Time Managers, if the
  85648. specified task record is active (that is, it has been activated but the
  85649. specified time has not yet elapsed), then the tmCount field of the task record
  85650. returns the amount of time remaining. To provide the greatest accuracy, the
  85651. unused time is reported as negated microseconds if that value is small enough to
  85652. fit into the tmCount field (even if the delay was originally specified in
  85653. milliseconds); otherwise, the unused time is reported in positive milliseconds.
  85654. If the time has already expired, tmCount contains 0.
  85655.  
  85656. Result codes
  85657. noErr  0  No error
  85658.  
  85659.  
  85660. æKY ToolUtils.h
  85661. æKL AngleFromSlope
  85662. BitAnd
  85663. BitClr
  85664. BitNot
  85665. BitOr
  85666. BitSet
  85667. BitShift
  85668. BitTst
  85669. BitXor
  85670. deltapoint
  85671. DeltaPoint
  85672. FixMul
  85673. FixRatio
  85674. FixRound
  85675. GetCursor
  85676. GetIcon
  85677. GetIndPattern
  85678. GetIndString
  85679. getindstring
  85680. GetPattern
  85681. GetPicture
  85682. GetString
  85683. HiWord
  85684. LongMul
  85685. LoWord
  85686. Munger
  85687. newstring
  85688. NewString
  85689. PackBits
  85690. PlotIcon
  85691. ScreenRes
  85692. SetString
  85693. setstring
  85694. shieldcursor
  85695. ShieldCursor
  85696. SlopeFromAngle
  85697. UnpackBits
  85698.  
  85699. crossCursor
  85700. iBeamCursor
  85701. Int64Bit
  85702. plusCursor
  85703. sysPatListID
  85704. watchCursor
  85705.  
  85706. æKY sysPatListID
  85707. æFc ToolUtils.h
  85708. æT #define
  85709. æD #define sysPatListID 0
  85710. æC 
  85711.  
  85712. æKY iBeamCursor
  85713. æFc ToolUtils.h
  85714. æT #define
  85715. æD #define iBeamCursor 1
  85716. æC 
  85717.  
  85718. æKY crossCursor
  85719. æFc ToolUtils.h
  85720. æT #define
  85721. æD #define crossCursor 2
  85722. æC 
  85723.  
  85724. æKY plusCursor
  85725. æFc ToolUtils.h
  85726. æT #define
  85727. æD #define plusCursor 3
  85728. æC 
  85729.  
  85730. æKY watchCursor
  85731. æFc ToolUtils.h
  85732. æT #define
  85733. æD #define watchCursor 4
  85734. æC 
  85735.  
  85736. æKY Int64Bit
  85737. æFc ToolUtils.h
  85738. æT struct
  85739. æD struct Int64Bit {
  85740.     long hiLong;
  85741.     long loLong;
  85742. };
  85743.  
  85744. typedef struct Int64Bit Int64Bit;
  85745. æC 
  85746.  
  85747. æKY FixRatio
  85748. æFc ToolUtils.h
  85749. æT Function
  85750. æTN A869
  85751. æD pascal Fixed FixRatio(short numer,short denom)
  85752.     = 0xA869; 
  85753. æDT Fixed myVariable = FixRatio((short) numer,(short) denom);
  85754. æRI I-467
  85755. æC  
  85756. FixRatio returns the fixed-point quotient of numer and denom. Numer or denom may be
  85757. any signed integer. The result is truncated. If denom is 0, FixRatio returns $7FFFFFFF
  85758. if numer is positive or $80000001 if numer is negative.
  85759.  
  85760. æKY FixMul
  85761. æFc ToolUtils.h
  85762. æT Function
  85763. æTN A868
  85764. æD pascal Fixed FixMul(Fixed a,Fixed b)
  85765.     = 0xA868; 
  85766. æDT Fixed myVariable = FixMul((Fixed) a,(Fixed) b);
  85767. æRI I-467
  85768. æC 
  85769. FixMul returns the signed fixed-point product of a and b. The result is computed MOD
  85770. 65536, truncated, and signed according to the signs of a and b.
  85771.  
  85772. æKY FixRound
  85773. æFc ToolUtils.h
  85774. æT Function
  85775. æTN A86C
  85776. æD pascal short FixRound(Fixed x)
  85777.     = 0xA86C; 
  85778. æDT short myVariable = FixRound((Fixed) x);
  85779. æRI I-467
  85780. æC 
  85781. Given a positive fixed-point number, FixRound rounds it to the nearest integer and
  85782. returns the result. If the value is halfway between two integers (.5), it’s rounded
  85783. up.
  85784.  
  85785. Note:  To round a negative fixed-point number, negate it, round,
  85786.        then negate it again.
  85787.  
  85788. æKY GetString
  85789. æFc ToolUtils.h
  85790. æT Function
  85791. æTN A9BA
  85792. æD pascal StringHandle GetString(short stringID)
  85793.     = 0xA9BA; 
  85794. æDT StringHandle myVariable = GetString((short) stringID);
  85795. æMM
  85796. æRI I-468
  85797. æC 
  85798. GetString returns a handle to the string having the given resource ID, reading it
  85799. from the resource file if necessary. It calls the Resource Manager function GetResource('STR
  85800. ',stringID). If the resource can’t be read, GetString returns NIL.
  85801.  
  85802. Note:  Like NewString, GetString returns a handle to a string whose size is
  85803.        based on its actual length.
  85804.  
  85805. Note:  If your application uses a large number of strings, storing them in
  85806.        a string list in the resource file will be more efficient. You can
  85807.        access strings in a string list with GetIndString, as described below.
  85808.  
  85809. æKY Munger
  85810. æFc ToolUtils.h
  85811. æT Function
  85812. æTN A9E0
  85813. æD pascal long Munger(Handle h,long offset,Ptr ptr1,long len1,Ptr ptr2,long len2)
  85814.     = 0xA9E0; 
  85815. æDT long myVariable = Munger((Handle) h,(long) offset,(Ptr) ptr1,(long) len1,(Ptr) ptr2,(long) len2);
  85816. æMM
  85817. æRI I-468
  85818. æC  
  85819. Munger (which rhymes with “plunger”) lets you manipulate bytes in the string of bytes
  85820. (the “destination string”) to which h is a handle. The operation starts at the specified
  85821. byte offset in the destination string.
  85822.  
  85823. Note:  Although the term “string” is used here, Munger does not assume it’s
  85824.        manipulating a Pascal string; if you pass it a handle to a Pascal
  85825.        string, you must take into account the length byte.
  85826.  
  85827. The exact nature of the operation done by Munger depends on the values you pass it in
  85828. two pointer/length parameter pairs. In general, (ptr1,len1) defines a target string
  85829. to be replaced by the second string (ptr2,len2). If these four parameters are all
  85830. positive and nonzero, Munger looks for the target string in the destination string,
  85831. starting from the given offset and ending at the end of the string; it replaces the
  85832. first occurrence it finds with the replacement string and returns the offset of the
  85833. first byte past where the replacement occurred. Figure 2 illustrates this; the bytes
  85834. represent ASCII characters as shown.
  85835.  
  85836. •••Refer to Figure 2.•••
  85837.  
  85838. Figure 2–Munger Function
  85839.  
  85840. Different operations occur if either pointer is NIL or either length is 0:
  85841.  
  85842.   •  If ptr1 is NIL, the substring of length len1 starting at the given
  85843.      offset is replaced by the replacement string. If len1 is negative, the
  85844.      substring from the given offset to the end of the destination string is
  85845.      replaced by the replacement string. In either case, Munger returns the
  85846.      offset of the first byte past where the replacement occurred.
  85847.   •  If len1 is 0, (ptr2,len2) is simply inserted at the given offset; no
  85848.      text is replaced. Munger returns the offset of the first byte past where
  85849.      the insertion occurred.
  85850.   •  If ptr2 is NIL, Munger returns the offset at which the target string
  85851.      was found. The destination string isn’t changed.
  85852.   •  If len2 is 0 (and ptr2 is not NIL), the target string is deleted rather
  85853.      than replaced (since the replacement string is empty). Munger returns
  85854.      the offset at which the deletion occurred.
  85855.  
  85856. If it can’t find the target string in the destination string, Munger returns a negative
  85857. value.
  85858.  
  85859. There’s one case in which Munger performs a replacement even if it doesn’t find all
  85860. of the target string. If the substring from the offset to the end of the destination
  85861. string matches the beginning of the target string, the portion found is replaced with
  85862. the replacement string.
  85863.  
  85864. Warning:  Be careful not to specify an offset that’s greater than the length
  85865.           of the destination string, or unpredictable results may occur.
  85866.  
  85867. Note:  The destination string must be in a relocatable block that was
  85868.        allocated by the Memory Manager. Munger accesses the string’s length
  85869.        by calling the Memory Manager routines GetHandleSize and SetHandleSize.
  85870.  
  85871. æKY PackBits
  85872. æFc ToolUtils.h
  85873. æT Function
  85874. æTN A8CF
  85875. æD pascal void PackBits(Ptr *srcPtr,Ptr *dstPtr,short srcBytes)
  85876.     = 0xA8CF; 
  85877. æDT PackBits((Ptr *) srcPtr,(Ptr *) dstPtr,(short) srcBytes);
  85878. æRT 86
  85879. æRI I-470, N86-2
  85880. æC  
  85881. PackBits compresses srcBytes bytes of data starting at srcPtr and stores the compressed
  85882. data at dstPtr. The value of srcBytes should not be greater than 127. Bytes are
  85883. compressed when there are three or more consecutive equal bytes. After the data is
  85884. compressed, srcPtr is incremented by srcBytes and dstPtr is incremented by the number
  85885. of bytes that the data was compressed to. In the worst case, the compressed data can
  85886. be one byte longer than the original data.
  85887.  
  85888. PackBits is usually used to compress QuickDraw bit images; in this case, you should
  85889. call it for one row at a time. (Because of the repeating patterns in QuickDraw images,
  85890. there are more likely to be consecutive equal bytes there than in other data.) Use
  85891. UnpackBits (below) to expand data compressed by PackBits.
  85892.  
  85893. æKY UnpackBits
  85894. æFc ToolUtils.h
  85895. æT Function
  85896. æTN A8D0
  85897. æD pascal void UnpackBits(Ptr *srcPtr,Ptr *dstPtr,short dstBytes)
  85898.     = 0xA8D0; 
  85899. æDT UnpackBits((Ptr *) srcPtr,(Ptr *) dstPtr,(short) dstBytes);
  85900. æRT 86
  85901. æRI I-470, N86-3
  85902. æC 
  85903. Given in srcPtr a pointer to data that was compressed by PackBits, UnpackBits expands
  85904. the data and stores the result at dstPtr. DstBytes is the length that the expanded
  85905. data will be; it should be the value that was passed to PackBits in the srcBytes
  85906. parameter. After the data is expanded, srcPtr is incremented by the number of bytes
  85907. that were expanded and dstPtr is incremented by dstBytes.
  85908.  
  85909. æKY BitTst
  85910. æFc ToolUtils.h
  85911. æT Function
  85912. æTN A85D
  85913. æD pascal Boolean BitTst(Ptr bytePtr,long bitNum)
  85914.     = 0xA85D; 
  85915. æDT Boolean myVariable = BitTst((Ptr) bytePtr,(long) bitNum);
  85916. æRI I-471
  85917. æC  
  85918. Given a pointer and an offset, these routines can manipulate any specific bit. The
  85919. pointer can point to an even or odd byte; the offset can be any positive long integer,
  85920. starting at 0 for the high-order bit of the specified byte (see Figure 3).
  85921.  
  85922. •••Refer to Figure 3.•••
  85923.  
  85924. Figure 3–Bit Numbering for Utility Routines
  85925.  
  85926. Note:  This bit numbering is the opposite of the MC68000 bit numbering to
  85927.        allow for greater generality. For example, you can directly access
  85928.        bit 1000 of a bit image given a pointer to the beginning of the bit
  85929.        image.
  85930.  
  85931. FUNCTION BitTst (bytePtr:  Ptr; bitNum:  LONGINT) :  BOOLEAN;
  85932.  
  85933. BitTst tests whether a given bit is set and returns TRUE if so or FALSE if not. The
  85934. bit is specified by bitNum, an offset from the high-order bit of the byte pointed to
  85935. by bytePtr.
  85936.  
  85937. æKY BitSet
  85938. æFc ToolUtils.h
  85939. æT Function
  85940. æTN A85E
  85941. æD pascal void BitSet(Ptr bytePtr,long bitNum)
  85942.     = 0xA85E; 
  85943. æDT BitSet((Ptr) bytePtr,(long) bitNum);
  85944. æRI I-471
  85945. æC 
  85946. Given a pointer and an offset, these routines can manipulate any specific bit. The
  85947. pointer can point to an even or odd byte; the offset can be any positive long integer,
  85948. starting at 0 for the high-order bit of the specified byte (see Figure 3).
  85949.  
  85950. •••Refer to Figure 3.•••
  85951.  
  85952. Figure 3–Bit Numbering for Utility Routines
  85953.  
  85954. Note:  This bit numbering is the opposite of the MC68000 bit numbering to
  85955.        allow for greater generality. For example, you can directly access
  85956.        bit 1000 of a bit image given a pointer to the beginning of the bit
  85957.        image.
  85958.  
  85959. BitSet sets the bit specified by bitNum, an offset from the high-order bit of the
  85960. byte pointed to by bytePtr.
  85961.  
  85962. æKY BitClr
  85963. æFc ToolUtils.h
  85964. æT Function
  85965. æTN A85F
  85966. æD pascal void BitClr(Ptr bytePtr,long bitNum)
  85967.     = 0xA85F; 
  85968. æDT BitClr((Ptr) bytePtr,(long) bitNum);
  85969. æRI I-471
  85970. æC 
  85971. Given a pointer and an offset, these routines can manipulate any specific bit. The
  85972. pointer can point to an even or odd byte; the offset can be any positive long integer,
  85973. starting at 0 for the high-order bit of the specified byte (see Figure 3).
  85974.  
  85975. •••Refer to Figure 3.•••
  85976.  
  85977. Figure 3–Bit Numbering for Utility Routines
  85978.  
  85979. Note:  This bit numbering is the opposite of the MC68000 bit numbering to
  85980.        allow for greater generality. For example, you can directly access
  85981.        bit 1000 of a bit image given a pointer to the beginning of the bit
  85982.        image.
  85983.  
  85984.  
  85985. BitSet clears the bit specified by bitNum, an offset from the high-order bit of the
  85986. byte pointed to by bytePtr.
  85987.  
  85988. æKY BitAnd
  85989. æFc ToolUtils.h
  85990. æT Function
  85991. æTN A858
  85992. æD pascal long BitAnd(long value1,long value2)
  85993.     = 0xA858; 
  85994. æDT long myVariable = BitAnd((long) value1,(long) value2);
  85995. æRI I-471
  85996. æC  
  85997. BitAnd returns the result of the AND logical operation on the bits comprising the
  85998. given long integers (value1 AND value2).
  85999.  
  86000. æKY BitOr
  86001. æFc ToolUtils.h
  86002. æT Function
  86003. æTN A85B
  86004. æD pascal long BitOr(long value1,long value2)
  86005.     = 0xA85B; 
  86006. æDT long myVariable = BitOr((long) value1,(long) value2);
  86007. æRI I-471
  86008. æC  
  86009. BitOr returns the result of the OR logical operation on the bits comprising given
  86010. long integers (value1 OR value2).
  86011.  
  86012. æKY BitXor
  86013. æFc ToolUtils.h
  86014. æT Function
  86015. æTN A859
  86016. æD pascal long BitXor(long value1,long value2)
  86017.     = 0xA859; 
  86018. æDT long myVariable = BitXor((long) value1,(long) value2);
  86019. æRI I-471
  86020. æC  
  86021. BitXor returns the result of the XOR logical operation on the bits comprising the
  86022. given long integers (value1 XOR value2).
  86023.  
  86024. æKY BitNot
  86025. æFc ToolUtils.h
  86026. æT Function
  86027. æTN A85A
  86028. æD pascal long BitNot(long value)
  86029.     = 0xA85A; 
  86030. æDT long myVariable = BitNot((long) value);
  86031. æRI I-471
  86032. æC 
  86033. BitNot returns the result of the NOT logical operation on the bits comprising the
  86034. given long integer (NOT value).
  86035.  
  86036. æKY BitShift
  86037. æFc ToolUtils.h
  86038. æT Function
  86039. æTN A85C
  86040. æD pascal long BitShift(long value,short count)
  86041.     = 0xA85C; 
  86042. æDT long myVariable = BitShift((long) value,(short) count);
  86043. æRI I-472
  86044. æC 
  86045. BitShift logically shifts the bits of the given long integer. The count parameter
  86046. specifies the direction and extent of the shift, and is taken MOD 32. If count is
  86047. positive, BitShift shifts that many positions to the left; if count is negative, it
  86048. shifts to the right. Zeroes are shifted into empty positions at either end.
  86049.  
  86050. æKY HiWord
  86051. æFc ToolUtils.h
  86052. æT Function
  86053. æTN A86A
  86054. æD pascal short HiWord(long x)
  86055.     = 0xA86A; 
  86056. æDT short myVariable = HiWord((long) x);
  86057. æRI I-472
  86058. æC  
  86059. HiWord returns the high-order word of the given long integer. One use of this function
  86060. is to extract the integer part of a fixed-point number.
  86061.  
  86062. æKY LoWord
  86063. æFc ToolUtils.h
  86064. æT Function
  86065. æTN A86B
  86066. æD pascal short LoWord(long x)
  86067.     = 0xA86B; 
  86068. æDT short myVariable = LoWord((long) x);
  86069. æRI I-472
  86070. æC 
  86071. LoWord returns the low-order word of the given long integer. One use of this function
  86072. is to extract the fractional part of a fixed-point number.
  86073.  
  86074. Note:  If you’re dealing with a long integer that contains two separate
  86075.        integer values, you can define a variant record instead of using
  86076.        HiWord and LoWord. For example, for fixed-point numbers, you could
  86077.        define the following type:
  86078.  
  86079. TYPE  FixedAndInt = RECORD CASE INTEGER OF
  86080.                       1:  (fixedView:  Fixed);
  86081.                       2:  (intView:    RECORD
  86082.                                          whole:  INTEGER;
  86083.                                          part:   INTEGER
  86084.                                        END;
  86085.                     END;
  86086.  
  86087. If you declare x to be of type FixedAndInt, you can access it as a fixed-point value
  86088. with x.fixedView, or access the integer part with x.intView.whole and the fractional
  86089. part with x.intView.part.
  86090.  
  86091. æKY LongMul
  86092. æFc ToolUtils.h
  86093. æT Function
  86094. æTN A867
  86095. æD pascal void LongMul(long a,long b,Int64Bit *dest)
  86096.     = 0xA867; 
  86097. æDT LongMul((long) a,(long) b,(Int64Bit *) dest);
  86098. æRI I-472
  86099. æC 
  86100. LongMul multiplies the given long integers and returns the signed result in dest,
  86101. which has the following data type:
  86102.  
  86103. TYPE  Int64Bit = RECORD
  86104.                    hiLong:  LONGINT;
  86105.                    loLong:  LONGINT
  86106.                  END;
  86107.  
  86108. æKY GetIcon
  86109. æFc ToolUtils.h
  86110. æT Function
  86111. æTN A9BB
  86112. æD pascal Handle GetIcon(short iconID)
  86113.     = 0xA9BB; 
  86114. æDT Handle myVariable = GetIcon((short) iconID);
  86115. æMM
  86116. æRT 55
  86117. æRI I-473, P-83, 172
  86118. æC 
  86119. GetIcon returns a handle to the icon having the given resource ID, reading it from
  86120. the resource file if necessary. It calls the Resource Manager function GetResource('ICON',iconID).
  86121. If the resource can’t be read, GetIcon returns NIL.
  86122.  
  86123. æKY PlotIcon
  86124. æFc ToolUtils.h
  86125. æT Function
  86126. æTN A94B
  86127. æD pascal void PlotIcon(const Rect *theRect,Handle theIcon)
  86128.     = 0xA94B; 
  86129. æDT PlotIcon((const Rect *) theRect,(Handle) theIcon);
  86130. æMM
  86131. æRT 55
  86132. æRI I-473, P-83, 179
  86133. æC 
  86134. PlotIcon draws the icon whose handle is theIcon in the rectangle theRect, which is in
  86135. the local coordinates of the current grafPort. It calls the QuickDraw procedure
  86136. CopyBits and uses the srcCopy transfer mode.
  86137.  
  86138. æKY GetPattern
  86139. æFc ToolUtils.h
  86140. æT Function
  86141. æTN A9B8
  86142. æD pascal PatHandle GetPattern(short patID)
  86143.     = 0xA9B8; 
  86144. æDT PatHandle myVariable = GetPattern((short) patID);
  86145. æMM
  86146. æRI I-473, P-81, 173
  86147. æC  
  86148. GetPattern returns a handle to the pattern having the given resource ID, reading it
  86149. from the resource file if necessary. It calls the Resource Manager function GetResource('PAT
  86150. ',patID). If the resource can’t be read, GetPattern returns NIL. The PatHandle data
  86151. type is defined in the Toolbox Utilities as follows:
  86152.  
  86153. TYPE  PatPtr    = ^Pattern;
  86154.       PatHandle = ^PatPtr;
  86155.  
  86156. æKY GetCursor
  86157. æFc ToolUtils.h
  86158. æT Function
  86159. æTN A9B9
  86160. æD pascal CursHandle GetCursor(short cursorID)
  86161.     = 0xA9B9; 
  86162. æDT CursHandle myVariable = GetCursor((short) cursorID);
  86163. æMM
  86164. æRI I-474, P-84, 171
  86165. æC 
  86166. GetCursor returns a handle to the cursor having the given resource ID, reading it
  86167. from the resource file if necessary. It calls the Resource Manager function GetResource('CURS',cursorID).
  86168. If the resource can’t be read, GetCursor returns NIL.
  86169.  
  86170. The CursHandle data type is defined in the Toolbox Utilities as follows:
  86171.  
  86172. TYPE  CursPtr    = ^Cursor;
  86173.       CursHandle = ^CursPtr;
  86174.  
  86175. The standard cursors shown in Figure 5 are defined in the system resource file. Their
  86176. resource IDs are:
  86177.  
  86178. CONST  iBeamCursor  = 1;    {to select text}
  86179.        crossCursor  = 2;    {to draw graphics}
  86180.        plusCursor   = 3;    {to select cells in structured documents}
  86181.        watchCursor  = 4;    {to indicate a long wait}
  86182.  
  86183. •••Refer to Figure 5.•••
  86184.  
  86185. Figure 5–Standard Cursors
  86186.  
  86187. Note:  You can set the cursor with the QuickDraw procedure SetCursor. The
  86188.        arrow cursor is defined in QuickDraw as a global variable named arrow.
  86189.  
  86190. æKY GetPicture
  86191. æFc ToolUtils.h
  86192. æT Function
  86193. æTN A9BC
  86194. æD pascal PicHandle GetPicture(short picID)
  86195.     = 0xA9BC; 
  86196. æDT PicHandle myVariable = GetPicture((short) picID);
  86197. æMM
  86198. æRI I-475, P-86, 173
  86199. æC 
  86200. GetPicture returns a handle to the picture having the given resource ID, reading it
  86201. from the resource file if necessary. It calls the Resource Manager function GetResource('PICT',picID).
  86202. If the resource can’t be read, GetPicture returns NIL. The PicHandle data type is
  86203. defined in QuickDraw.
  86204.  
  86205. æKY SlopeFromAngle
  86206. æFc ToolUtils.h
  86207. æT Function
  86208. æTN A8BC
  86209. æD pascal Fixed SlopeFromAngle(short angle)
  86210.     = 0xA8BC; 
  86211. æDT Fixed myVariable = SlopeFromAngle((short) angle);
  86212. æRI I-475
  86213. æC 
  86214. Given an angle, SlopeFromAngle returns the slope dh/dv of the line forming that angle
  86215. with the y-axis (dh/dv is the horizontal change divided by the vertical change between
  86216. any two points on the line). Figure 6 illustrates SlopeFromAngle (and AngleFromSlope,
  86217. described below, which does the reverse). The angle is treated MOD 180, and is in
  86218. degrees measured from 12 o’clock; positive degrees are measured clockwise, negative
  86219. degrees are measured counterclockwise (for example, 90 degrees is at 3 o’clock and
  86220. –90 degrees is at 9 o’clock). Positive y is down; positive x is to the right.
  86221.  
  86222. •••Refer to Figure 6.•••
  86223.  
  86224. Figure 6–SlopeFromAngle and AngleFromSlope
  86225.  
  86226. æKY AngleFromSlope
  86227. æFc ToolUtils.h
  86228. æT Function
  86229. æTN A8C4
  86230. æD pascal short AngleFromSlope(Fixed slope)
  86231.     = 0xA8C4; 
  86232. æDT short myVariable = AngleFromSlope((Fixed) slope);
  86233. æRI I-476
  86234. æC 
  86235. Given the slope dh/dv of a line (see SlopeFromAngle above), AngleFromSlope returns
  86236. the angle formed by that line and the y-axis. The angle returned is between 1 and 180
  86237. (inclusive), in degrees measured clockwise from 12 o’clock.
  86238.  
  86239. AngleFromSlope is meant for use when speed is much more important than accuracy—its
  86240. integer result is guaranteed to be within one degree of the correct answer, but not
  86241. necessarily within half a degree. However, the equation
  86242.  
  86243.   AngleFromSlope(SlopeFromAngle(x)) = x
  86244.  
  86245. is true for all x except 0 (although its reverse is not).
  86246.  
  86247. Note:  SlopeFromAngle(0) is 0, and AngleFromSlope(0) is 180.
  86248.  
  86249. æKY newstring
  86250. æFc ToolUtils.h
  86251. æT Function
  86252. æD StringHandle newstring(char *theString); 
  86253. æDT StringHandle myVariable = newstring((char *) theString);
  86254. æRI I-468
  86255. æC  
  86256. NewString allocates the specified string as a relocatable object in the heap and
  86257. returns a handle to it.
  86258.  
  86259. Note:  NewString returns a handle to a string whose size is based on its
  86260.        actual length (not necessarily 255); if you’re going to use Pascal
  86261.        string functions that could change the length of the string, you may
  86262.        want to call SetString or the Memory Manager procedure SetHandleSize
  86263.        first to set the string to the maximum size.
  86264.  
  86265. æKY SetString
  86266. æFc ToolUtils.h
  86267. æT Function
  86268. æTN A907
  86269. æD pascal void SetString(StringHandle theString,const Str255 strNew)
  86270.     = 0xA907; 
  86271. æDT SetString((StringHandle) theString,(const Str255) strNew);
  86272. æMM
  86273. æRI I-468
  86274. æC 
  86275. SetString sets the string whose handle is passed in h to the string specified by
  86276. theString.
  86277.  
  86278. æKY DeltaPoint
  86279. æFc ToolUtils.h
  86280. æT Function
  86281. æTN A94F
  86282. æD pascal long DeltaPoint(Point ptA,Point ptB)
  86283.     = 0xA94F; 
  86284. æDT long myVariable = DeltaPoint((Point) ptA,(Point) ptB);
  86285. æRI I-475
  86286. æC 
  86287. DeltaPoint subtracts the coordinates of ptB from the coordinates of ptA. The high-order
  86288. word of the result is the difference of the vertical coordinates and the low-order
  86289. word is the difference of the horizontal coordinates.
  86290.  
  86291. Note:  The QuickDraw procedure SubPt also subtracts the coordinates of one
  86292.        point from another, but returns the result in a VAR parameter of type
  86293.        Point.
  86294.  
  86295. æKY NewString
  86296. æFc ToolUtils.h
  86297. æT Function
  86298. æTN A906
  86299. æD pascal StringHandle NewString(const Str255 theString)
  86300.     = 0xA906; 
  86301. æDT StringHandle myVariable = NewString((const Str255) theString);
  86302. æMM
  86303. æRI I-468
  86304. æC  
  86305. NewString allocates the specified string as a relocatable object in the heap and
  86306. returns a handle to it.
  86307.  
  86308. Note:  NewString returns a handle to a string whose size is based on its
  86309.        actual length (not necessarily 255); if you’re going to use Pascal
  86310.        string functions that could change the length of the string, you may
  86311.        want to call SetString or the Memory Manager procedure SetHandleSize
  86312.        first to set the string to the maximum size.
  86313.  
  86314. æKY ShieldCursor
  86315. æFc ToolUtils.h
  86316. æT Function
  86317. æTN A855
  86318. æD pascal void ShieldCursor(const Rect *shieldRect,Point offsetPt)
  86319.     = 0xA855; 
  86320. æDT ShieldCursor((const Rect *) shieldRect,(Point) offsetPt);
  86321. æRI I-474
  86322. æC 
  86323. If the cursor and the given rectangle intersect, ShieldCursor hides the cursor. If
  86324. they don’t intersect, the cursor remains visible while the mouse isn’t moving, but is
  86325. hidden when the mouse moves.
  86326.  
  86327. Like the QuickDraw procedure HideCursor, ShieldCursor decrements the cursor level,
  86328. and should be balanced by a call to ShowCursor.
  86329.  
  86330. The rectangle may be given in global or local coordinates:
  86331.  
  86332.   •  If they’re global coordinates, pass (0,0) in offsetPt. If they’re a
  86333.      grafPort’s local coordinates, pass the top left corner of the grafPort’s
  86334.      boundary rectangle in offsetPt. (Like the QuickDraw procedure
  86335.      LocalToGlobal, ShieldCursor will offset the coordinates of the rectangle
  86336.      by the coordinates of this point.)
  86337.  
  86338. æKY GetIndString
  86339. æFc ToolUtils.h
  86340. æT Function
  86341. æD pascal void GetIndString(Str255 theString,short strListID,short index); 
  86342. æDT GetIndString((Str255) theString,(short) strListID,(short) index);
  86343. æMM
  86344. æRI I-468
  86345. æC 
  86346. [Not in ROM]
  86347.  
  86348. GetIndString returns in theString a string in the string list that has the resource
  86349. ID strListID. It reads the string list from the resource file if necessary, by calling
  86350. the Resource Manager function GetResource('STR#',strListID). It returns the string
  86351. specified by the index parameter, which can range from 1 to the number of strings in
  86352. the list. If the resource can’t be read or the index is out of range, the empty
  86353. string is returned.
  86354.  
  86355. æKY getindstring
  86356. æFc ToolUtils.h
  86357. æT Function
  86358. æD void getindstring(char *theString,short strListID,short index); 
  86359. æDT getindstring((char *) theString,(short) strListID,(short) index);
  86360. æC 
  86361.  
  86362. æKY ScreenRes
  86363. æFc ToolUtils.h
  86364. æT Function
  86365. æD pascal void ScreenRes(short *scrnHRes,short *scrnVRes); 
  86366. æDT ScreenRes((short *) scrnHRes,(short *) scrnVRes);
  86367. æRI I-473
  86368. æC  
  86369. ScreenRes returns the resolution of the screen of the Macintosh being used. ScrnHRes
  86370. and scrnVRes are the number of pixels per inch horizontally and vertically, respectively.
  86371.  
  86372. Assembly-language note:  The number of pixels per inch horizontally is stored
  86373.                          in the global variable ScrHRes, and the number of
  86374.                          pixels per inch vertically is stored in ScrVRes.
  86375.  
  86376. æKY GetIndPattern
  86377. æFc ToolUtils.h
  86378. æT Function
  86379. æD pascal void GetIndPattern(Pattern *thePat,short patListID,short index); 
  86380. æDT GetIndPattern((Pattern *) thePat,(short) patListID,(short) index);
  86381. æMM
  86382. æRI I-473, P-81
  86383. æC 
  86384. GetIndPattern returns in thePattern a pattern in the pattern list that has the resource
  86385. ID patListID. It reads the pattern list from the resource file if necessary, by
  86386. calling the Resource Manager function GetResource('PAT#',patListID). It returns the
  86387. pattern specified by the index parameter, which can range from 1 to the number of
  86388. patterns in the pattern list.
  86389.  
  86390. There’s a pattern list in the system resource file that contains the standard Macintosh
  86391. patterns used by MacPaint (see Figure 4). Its resource ID is:
  86392.  
  86393.   CONST sysPatListID = 0;
  86394.  
  86395. •••Refer to Figure 4.•••
  86396.  
  86397. Figure 4–Standard Patterns
  86398.  
  86399. æKY setstring
  86400. æFc ToolUtils.h
  86401. æT Function
  86402. æD void setstring(StringHandle theString,char *strNew); 
  86403. æDT setstring((StringHandle) theString,(char *) strNew);
  86404. æMM
  86405. æRI I-468
  86406. æC 
  86407. SetString sets the string whose handle is passed in h to the string specified by
  86408. theString.
  86409.  
  86410. æKY shieldcursor
  86411. æFc ToolUtils.h
  86412. æT Function
  86413. æD void shieldcursor(const Rect *shieldRect,Point *offsetPt); 
  86414. æDT shieldcursor((const Rect *) shieldRect,(Point *) offsetPt);
  86415. æRI I-474
  86416. æC 
  86417. If the cursor and the given rectangle intersect, ShieldCursor hides the cursor. If
  86418. they don’t intersect, the cursor remains visible while the mouse isn’t moving, but is
  86419. hidden when the mouse moves.
  86420.  
  86421. Like the QuickDraw procedure HideCursor, ShieldCursor decrements the cursor level,
  86422. and should be balanced by a call to ShowCursor.
  86423.  
  86424. The rectangle may be given in global or local coordinates:
  86425.  
  86426.   •  If they’re global coordinates, pass (0,0) in offsetPt. If they’re a
  86427.      grafPort’s local coordinates, pass the top left corner of the grafPort’s
  86428.      boundary rectangle in offsetPt. (Like the QuickDraw procedure
  86429.      LocalToGlobal, ShieldCursor will offset the coordinates of the rectangle
  86430.      by the coordinates of this point.)
  86431.  
  86432. æKY deltapoint
  86433. æFc ToolUtils.h
  86434. æT Function
  86435. æD long deltapoint(Point *ptA,Point *ptB); 
  86436. æDT long myVariable = deltapoint((Point *) ptA,(Point *) ptB);
  86437. æRI I-475
  86438. æC 
  86439. DeltaPoint subtracts the coordinates of ptB from the coordinates of ptA. The high-order
  86440. word of the result is the difference of the vertical coordinates and the low-order
  86441. word is the difference of the horizontal coordinates.
  86442.  
  86443. Note:  The QuickDraw procedure SubPt also subtracts the coordinates of one
  86444.        point from another, but returns the result in a VAR parameter of type
  86445.        Point.
  86446.  
  86447.  
  86448. æKY Types.h
  86449. æKL Debugger
  86450. DebugStr
  86451. debugstr
  86452. SysBreak
  86453. SysBreakFunc
  86454. SysBreakStr
  86455.  
  86456. (ProcPtr)()
  86457. Boolean
  86458. Byte
  86459. false
  86460. Fixed
  86461. Fract
  86462. h
  86463. nil
  86464. noErr
  86465. OSErr
  86466. OSType
  86467. Point
  86468. ProcHandle
  86469. Ptr
  86470. Rect
  86471. ResType
  86472. SignedByte
  86473. Str255
  86474. Style
  86475. true
  86476. v
  86477. VHSelect
  86478.  
  86479. æKY nil
  86480. æFc Types.h
  86481. æT #define
  86482. æD #ifndef NULL
  86483. #define NULL 0
  86484. #endif
  86485. #define nil 0
  86486. æC 
  86487.  
  86488. æKY noErr
  86489. æFc Types.h
  86490. æT #define
  86491. æD #define noErr 0 /*All is well*/
  86492. æC 
  86493.  
  86494. æKY Boolean
  86495. false
  86496. true
  86497. æFc Types.h
  86498. æT enum
  86499. æD enum {false,true};
  86500. typedef unsigned char Boolean;
  86501. æC 
  86502.  
  86503. æKY VHSelect
  86504. v
  86505. h
  86506. æFc Types.h
  86507. æT enum
  86508. æD enum {v,h};
  86509. typedef unsigned char VHSelect;
  86510. æC You can store the coordinates of a point into a Pascal variable of type Point, defined
  86511. by QuickDraw as a record of two integers:
  86512.  
  86513. TYPE  VHSelect  =  (v,h);
  86514.       Point     =  RECORD CASE INTEGER OF
  86515.                      0:  (v:  INTEGER:     {vertical coordinate}
  86516.                           h:  INTEGER);    {horizontal coordinate}
  86517.                      1:  (vh:  ARRAY[VHSelect] OF INTEGER)
  86518.                    END;
  86519.  
  86520. •••Refer to Figure 3.•••
  86521.  
  86522. Figure 3–Points and Pixels
  86523.  
  86524. The variant part of this record lets you access the vertical and horizontal coordinates
  86525. of a point either individually or as an array. For example, if the variable goodPt is
  86526. declared to be of type Point, the following will all refer to the coordinates of the
  86527. point:
  86528.  
  86529.   goodPt.v            goodPt.h
  86530.   goodPt.vh[v]        goodPt.vh[h]
  86531.  
  86532. æKY (ProcPtr)()
  86533. æFc Types.h
  86534. æT typedef
  86535. æD typedef long (*ProcPtr)();
  86536. æC 
  86537.  
  86538. æKY Byte
  86539. æFc Types.h
  86540. æT typedef
  86541. æD typedef unsigned char Byte;
  86542. æC 
  86543. _______________________________________________________________________________
  86544.  
  86545. »General-Purpose Data Types
  86546. _______________________________________________________________________________
  86547.  
  86548. The Memory Manager includes a number of type definitions for general-purpose use. For
  86549. working with pointers and handles, there are the following definitions:
  86550.  
  86551. TYPE  SignedByte  = -128..127;
  86552.       Byte        = 0..255;
  86553.       Ptr         = ^SignedByte;
  86554.       Handle      = ^Ptr;
  86555.  
  86556. SignedByte stands for an arbitrary byte in memory, just to give Ptr and Handle something
  86557. to point to. You can define a buffer of, say, bufSize untyped memory bytes as a
  86558. PACKED ARRAY[1..bufSize] OF SignedByte. Byte is an alternative definition that treats
  86559. byte-length data as unsigned rather than signed quantities.
  86560.  
  86561. æKY SignedByte
  86562. æFc Types.h
  86563. æT typedef
  86564. æD typedef char SignedByte;
  86565. æC 
  86566. _______________________________________________________________________________
  86567.  
  86568. »General-Purpose Data Types
  86569. _______________________________________________________________________________
  86570.  
  86571. The Memory Manager includes a number of type definitions for general-purpose use. For
  86572. working with pointers and handles, there are the following definitions:
  86573.  
  86574. TYPE  SignedByte  = -128..127;
  86575.       Byte        = 0..255;
  86576.       Ptr         = ^SignedByte;
  86577.       Handle      = ^Ptr;
  86578.  
  86579. SignedByte stands for an arbitrary byte in memory, just to give Ptr and Handle something
  86580. to point to. You can define a buffer of, say, bufSize untyped memory bytes as a
  86581. PACKED ARRAY[1..bufSize] OF SignedByte. Byte is an alternative definition that treats
  86582. byte-length data as unsigned rather than signed quantities.
  86583.  
  86584. æKY Fixed
  86585. æFc Types.h
  86586. æT typedef
  86587. æD typedef long Fixed;
  86588. æC 
  86589. Finally, for treating long integers as fixed-point numbers, there’s the following
  86590. data type:
  86591.  
  86592. TYPE Fixed = LONGINT;
  86593.  
  86594. As illustrated in Figure 7, a fixed-point number is a 32-bit signed quantity containing
  86595. an integer part in the high-order word and a fractional part in the low-order word.
  86596. Negative numbers are the two’s complement; they’re formed by treating the fixed-point
  86597. number as a long integer, inverting each bit, and adding 1 to the least significant
  86598. bit.
  86599.  
  86600. •••Refer to Figure 7.•••
  86601.  
  86602. Figure 7–Fixed-Point Number
  86603.  
  86604. æKY Fract
  86605. æFc Types.h
  86606. æT typedef
  86607. æD typedef long Fract;
  86608. æC 
  86609.  
  86610. æKY OSErr
  86611. æFc Types.h
  86612. æT typedef
  86613. æD typedef short OSErr;
  86614. æC 
  86615.  
  86616. æKY OSType
  86617. æFc Types.h
  86618. æT typedef
  86619. æD typedef unsigned long OSType;
  86620. æC 
  86621.  
  86622. æKY ProcHandle
  86623. æFc Types.h
  86624. æT typedef
  86625. æD typedef ProcPtr *ProcHandle;
  86626. æC 
  86627.  
  86628. æKY Ptr
  86629. æFc Types.h
  86630. æT typedef
  86631. æD typedef char *Ptr;
  86632. typedef Ptr *Handle;
  86633. æC 
  86634.  
  86635. æKY ResType
  86636. æFc Types.h
  86637. æT typedef
  86638. æD typedef unsigned long ResType;
  86639. æC 
  86640.  
  86641. æKY Str255
  86642. æFc Types.h
  86643. æT typedef
  86644. æD typedef unsigned char Str255[256],Str63[64],Str31[32],Str27[28],Str15[16],*StringPtr,**StringHandle;
  86645.  
  86646. #ifdef __cplusplus
  86647. inline int Length(const StringPtr string) { return (*string); };
  86648. #else
  86649. #define Length(string) (*(unsigned char *)(string))
  86650. #endif
  86651.  
  86652. æC For working with strings, pointers to strings, and handles to strings, the Memory
  86653. Manager includes the following definitions:
  86654.  
  86655. TYPE  Str255        = STRING[255];
  86656.       StringPtr     = ^Str255;
  86657.       StringHandle  = ^StringPtr;
  86658.  
  86659. æKY Style
  86660. æFc Types.h
  86661. æT typedef
  86662. æD typedef unsigned char Style;
  86663. æC 
  86664.  
  86665. æKY Point
  86666. æFc Types.h
  86667. æT struct
  86668. æD struct Point {
  86669.     short v;
  86670.     short h;
  86671. };
  86672.  
  86673. typedef struct Point Point;
  86674. æC 
  86675.  
  86676. æKY Rect
  86677. æFc Types.h
  86678. æT struct
  86679. æD struct Rect {
  86680.     short top;
  86681.     short left;
  86682.     short bottom;
  86683.     short right;
  86684. };
  86685.  
  86686. typedef struct Rect Rect;
  86687. æC 
  86688. _______________________________________________________________________________
  86689.  
  86690. »Rectangles
  86691.  
  86692. Any two points can define the top left and bottom right corners of a rectangle. As
  86693. these points are infinitely small, the borders of the rectangle are infinitely thin
  86694. (see Figure 4).
  86695.  
  86696. •••Refer to Figure 4.•••
  86697.  
  86698. Figure 4–A Rectangle
  86699.  
  86700. Rectangles are used to define active areas on the screen, to assign coordinate systems
  86701. to graphic entities, and to specify the locations and sizes for various drawing
  86702. commands. QuickDraw also allows you to perform many mathematical calculations on
  86703. rectangles—changing their sizes, shifting them around, and so on.
  86704.  
  86705. Note:  Remember that rectangles, like points, are mathematical concepts
  86706.        that have no direct representation on the screen. The association
  86707.        between these conceptual elements and their physical representations
  86708.        is made by the BitMap data type, described in the following section.
  86709.  
  86710. The data type for rectangles is called Rect, and consists of four integers or two
  86711. points:
  86712.  
  86713. TYPE Rect = RECORD CASE INTEGER OF
  86714.               0:  (top:     INTEGER;
  86715.                    left:    INTEGER;
  86716.                    bottom:  INTEGER;
  86717.                    right:   INTEGER);
  86718.               1:  (topLeft:   Point;
  86719.                    botRight:  Point)
  86720.             END;
  86721.  
  86722. Again, the record variant allows you to access a variable of type Rect either as four
  86723. boundary coordinates or as two diagonally opposite corner points. Combined with the
  86724. record variant for points, all of the following references to the rectangle named
  86725. aRect are legal:
  86726.  
  86727. aRect                                           {type Rect}
  86728.  
  86729. aRect.topLeft           aRect.botRight          {type Point}
  86730.  
  86731. aRect.top               aRect.left              {type INTEGER}
  86732. aRect.topLeft.v         aRect.topLeft.h         {type INTEGER}
  86733. aRect.topLeft.vh[v]     aRect.topLeft.vh[h]     {type INTEGER}
  86734.  
  86735. aRect.bottom            aRect.right             {type INTEGER}
  86736. aRect.botRight.v        aRect.botRight.h        {type INTEGER}
  86737. aRect.botRight.vh[v]    aRect.botRight.vh[h]    {type INTEGER}
  86738.  
  86739. Note:  If the bottom coordinate of a rectangle is equal to or less than
  86740.        the top, or the right coordinate is equal to or less than the left,
  86741.        the rectangle is an empty rectangle (that is, one that contains no bits).
  86742.  
  86743. æKY Debugger
  86744. æFc Types.h
  86745. æT Function
  86746. æTN A9FF
  86747. æD pascal void Debugger(void)
  86748.     = 0xA9FF; 
  86749. æDT Debugger()(void);
  86750. æRT 145
  86751. æC 
  86752.  
  86753. æKY DebugStr
  86754. æFc Types.h
  86755. æT Function
  86756. æTN ABFF
  86757. æD pascal void DebugStr(StringPtr aStr)
  86758.     = 0xABFF; 
  86759. æDT DebugStr((StringPtr) aStr);
  86760. æC 
  86761.  
  86762. æKY debugstr
  86763. æFc Types.h
  86764. æT Function
  86765. æTN ABFF
  86766. æD void debugstr(char *aStr); 
  86767. æDT debugstr((char *) aStr);
  86768. æC 
  86769.  
  86770. æKY SysBreak
  86771. æFc Types.h
  86772. æT Function
  86773. æD pascal void SysBreak(void)
  86774.     = {0x303C,0xFE16,0xA9C9}; 
  86775. æDT SysBreak()(void);
  86776. æC 
  86777.  
  86778. æKY SysBreakStr
  86779. æFc Types.h
  86780. æT Function
  86781. æD pascal void SysBreakStr(StringPtr debugStr)
  86782.     = {0x303C,0xFE15,0xA9C9}; 
  86783. æDT SysBreakStr((StringPtr) debugStr);
  86784. æC 
  86785.  
  86786. æKY SysBreakFunc
  86787. æFc Types.h
  86788. æT Function
  86789. æD pascal void SysBreakFunc(StringPtr debugFunc)
  86790.     = {0x303C,0xFE14,0xA9C9}; 
  86791. æDT SysBreakFunc((StringPtr) debugFunc);
  86792. æC 
  86793.  
  86794.  
  86795. æKY Video.h
  86796. æKL 
  86797. cscGetEntries
  86798. cscGetMode
  86799. cscGetPageBase
  86800. cscGetPageCnt
  86801. cscGrayPage
  86802. cscReset
  86803. cscSetEntries
  86804. cscSetGray
  86805. cscSetMode
  86806. eightBitMode
  86807. fourBitMode
  86808. mBaseOffset
  86809. mBounds
  86810. mCmpCount
  86811. mCmpSize
  86812. mDevType
  86813. mHRes
  86814. mPageCnt
  86815. mPixelSize
  86816. mPixelType
  86817. mPlaneBytes
  86818. mRowBytes
  86819. mTable
  86820. mVersion
  86821. mVertRefRate
  86822. mVidParams
  86823. mVRes
  86824. oneBitMode
  86825. secondaryINIT
  86826. sixteenBitMode
  86827. spGammaDir
  86828. thirtyTwoBitMode
  86829. twoBitMode
  86830. VDEntRecPtr
  86831. VDEntryRecord
  86832. VDGrayPtr
  86833. VDGrayRecord
  86834. VDPageInfo
  86835. VDPgInfoPtr
  86836. VDSetEntryPtr
  86837. VDSetEntryRecord
  86838. VDSettings
  86839. VDSettingsPtr
  86840. VDSizeInfo
  86841. VDSzInfoPtr
  86842. VPBlock
  86843. VPBlockPtr
  86844.  
  86845. æKY mBaseOffset
  86846. æFc Video.h
  86847. æT #define
  86848. æD #define mBaseOffset 1 /*Id of mBaseOffset.*/
  86849. æC 
  86850.  
  86851. æKY mRowBytes
  86852. æFc Video.h
  86853. æT #define
  86854. æD #define mRowBytes 2 /*Video sResource parameter Id's */
  86855. æC 
  86856.  
  86857. æKY mBounds
  86858. æFc Video.h
  86859. æT #define
  86860. æD #define mBounds 3 /*Video sResource parameter Id's */
  86861. æC 
  86862.  
  86863. æKY mVersion
  86864. æFc Video.h
  86865. æT #define
  86866. æD #define mVersion 4 /*Video sResource parameter Id's */
  86867. æC 
  86868.  
  86869. æKY mHRes
  86870. æFc Video.h
  86871. æT #define
  86872. æD #define mHRes 5 /*Video sResource parameter Id's */
  86873. æC 
  86874.  
  86875. æKY mVRes
  86876. æFc Video.h
  86877. æT #define
  86878. æD #define mVRes 6 /*Video sResource parameter Id's */
  86879. æC 
  86880.  
  86881. æKY mPixelType
  86882. æFc Video.h
  86883. æT #define
  86884. æD #define mPixelType 7 /*Video sResource parameter Id's */
  86885. æC 
  86886.  
  86887. æKY mPixelSize
  86888. æFc Video.h
  86889. æT #define
  86890. æD #define mPixelSize 8 /*Video sResource parameter Id's */
  86891. æC 
  86892.  
  86893. æKY mCmpCount
  86894. æFc Video.h
  86895. æT #define
  86896. æD #define mCmpCount 9 /*Video sResource parameter Id's */
  86897. æC 
  86898.  
  86899. æKY mCmpSize
  86900. æFc Video.h
  86901. æT #define
  86902. æD #define mCmpSize 10 /*Video sResource parameter Id's */
  86903. æC 
  86904.  
  86905. æKY mPlaneBytes
  86906. æFc Video.h
  86907. æT #define
  86908. æD #define mPlaneBytes 11 /*Video sResource parameter Id's */
  86909. æC 
  86910.  
  86911. æKY mVertRefRate
  86912. æFc Video.h
  86913. æT #define
  86914. æD #define mVertRefRate 14 /*Video sResource parameter Id's */
  86915. æC 
  86916.  
  86917. æKY mVidParams
  86918. æFc Video.h
  86919. æT #define
  86920. æD #define mVidParams 1 /*Video parameter block id.*/
  86921. æC 
  86922.  
  86923. æKY mTable
  86924. æFc Video.h
  86925. æT #define
  86926. æD #define mTable 2 /*Offset to the table.*/
  86927. æC 
  86928.  
  86929. æKY mPageCnt
  86930. æFc Video.h
  86931. æT #define
  86932. æD #define mPageCnt 3 /*Number of pages*/
  86933. æC 
  86934.  
  86935. æKY mDevType
  86936. æFc Video.h
  86937. æT #define
  86938. æD #define mDevType 4 /*Device Type*/
  86939. æC 
  86940.  
  86941. æKY oneBitMode
  86942. æFc Video.h
  86943. æT #define
  86944. æD #define oneBitMode 128 /*Id of OneBitMode Parameter list.*/
  86945. æC 
  86946.  
  86947. æKY twoBitMode
  86948. æFc Video.h
  86949. æT #define
  86950. æD #define twoBitMode 129 /*Id of TwoBitMode Parameter list.*/
  86951. æC 
  86952.  
  86953. æKY fourBitMode
  86954. æFc Video.h
  86955. æT #define
  86956. æD #define fourBitMode 130 /*Id of FourBitMode Parameter list.*/
  86957. æC 
  86958.  
  86959. æKY eightBitMode
  86960. æFc Video.h
  86961. æT #define
  86962. æD #define eightBitMode 131 /*Id of EightBitMode Parameter list.*/
  86963. æC 
  86964.  
  86965. æKY sixteenBitMode
  86966. æFc Video.h
  86967. æT #define
  86968. æD #define sixteenBitMode 132 /*Id of SixteenBitMode Parameter list.*/
  86969. æC 
  86970.  
  86971. æKY thirtyTwoBitMode
  86972. æFc Video.h
  86973. æT #define
  86974. æD #define thirtyTwoBitMode 133 /*Id of ThirtyTwoBitMode Parameter list.*/
  86975. æC 
  86976.  
  86977. æKY cscReset
  86978. æFc Video.h
  86979. æT #define
  86980. æD #define cscReset 0 /*Control Codes*/
  86981. æC 
  86982.  
  86983. æKY cscSetMode
  86984. æFc Video.h
  86985. æT #define
  86986. æD #define cscSetMode 2 /*Control Codes*/
  86987. æC 
  86988.  
  86989. æKY cscSetEntries
  86990. æFc Video.h
  86991. æT #define
  86992. æD #define cscSetEntries 3 /*Control Codes*/
  86993. æC 
  86994.  
  86995. æKY cscGrayPage
  86996. æFc Video.h
  86997. æT #define
  86998. æD #define cscGrayPage 5
  86999. æC 
  87000.  
  87001. æKY cscSetGray
  87002. æFc Video.h
  87003. æT #define
  87004. æD #define cscSetGray 6
  87005. æC 
  87006.  
  87007. æKY cscGetMode
  87008. æFc Video.h
  87009. æT #define
  87010. æD #define cscGetMode 2 /*Status Codes*/
  87011. æC 
  87012.  
  87013. æKY cscGetEntries
  87014. æFc Video.h
  87015. æT #define
  87016. æD #define cscGetEntries 3 /*Status Codes*/
  87017. æC 
  87018.  
  87019. æKY cscGetPageCnt
  87020. æFc Video.h
  87021. æT #define
  87022. æD #define cscGetPageCnt 4 /*Status Codes*/
  87023. æC 
  87024.  
  87025. æKY cscGetPageBase
  87026. æFc Video.h
  87027. æT #define
  87028. æD #define cscGetPageBase 5 /*Status Codes*/
  87029. æC 
  87030.  
  87031. æKY secondaryINIT
  87032. æFc Video.h
  87033. æT #define
  87034. æD #define secondaryINIT 38
  87035. æC 
  87036.  
  87037. æKY spGammaDir
  87038. æFc Video.h
  87039. æT #define
  87040. æD #define spGammaDir 64
  87041. æC 
  87042.  
  87043. æKY VPBlock
  87044. VPBlockPtr
  87045. æFc Video.h
  87046. æT struct
  87047. æD struct VPBlock {
  87048.     long vpBaseOffset; /*Offset to page zero of video RAM (From minorBaseOS).*/
  87049.     short vpRowBytes; /*Width of each row of video memory.*/
  87050.     Rect vpBounds; /*BoundsRect for the video display (gives dimensions).*/
  87051.     short vpVersion; /*PixelMap version number.*/
  87052.     short vpPackType;
  87053.     long vpPackSize;
  87054.     long vpHRes; /*Horizontal resolution of the device (pixels per inch).*/
  87055.     long vpVRes; /*Vertical resolution of the device (pixels per inch).*/
  87056.     short vpPixelType; /*Defines the pixel type.*/
  87057.     short vpPixelSize; /*Number of bits in pixel.*/
  87058.     short vpCmpCount; /*Number of components in pixel.*/
  87059.     short vpCmpSize; /*Number of bits per component*/
  87060.     long vpPlaneBytes; /*Offset from one plane to the next.*/
  87061. };
  87062.  
  87063. typedef struct VPBlock VPBlock;
  87064. typedef VPBlock *VPBlockPtr;
  87065.  
  87066. æC 
  87067.  
  87068. æKY VDEntryRecord
  87069. VDEntRecPtr
  87070. æFc Video.h
  87071. æT struct
  87072. æD struct VDEntryRecord {
  87073.     Ptr csTable; /*(long) pointer to color table entry=value, r,g,b:INTEGER*/
  87074. };
  87075.  
  87076. typedef struct VDEntryRecord VDEntryRecord;
  87077. typedef VDEntryRecord *VDEntRecPtr;
  87078.  
  87079. æC 
  87080.  
  87081. æKY VDGrayRecord
  87082. VDGrayPtr
  87083. æFc Video.h
  87084. æT struct
  87085. æD struct VDGrayRecord {
  87086.     Boolean csMode; /*Same as GDDevType value (0=mono, 1=color)*/
  87087. };
  87088.  
  87089. typedef struct VDGrayRecord VDGrayRecord;
  87090. typedef VDGrayRecord *VDGrayPtr;
  87091.  
  87092. /* Parm block for SetGray control call */
  87093. æC 
  87094.  
  87095. æKY VDSetEntryRecord
  87096. VDSetEntryPtr
  87097. æFc Video.h
  87098. æT struct
  87099. æD struct VDSetEntryRecord {
  87100.     ColorSpec *csTable; /*Pointer to an array of color specs*/
  87101.     short csStart; /*Which spec in array to start with, or -1*/
  87102.     short csCount; /*Number of color spec entries to set*/
  87103. };
  87104.  
  87105. typedef struct VDSetEntryRecord VDSetEntryRecord;
  87106. typedef VDSetEntryRecord *VDSetEntryPtr;
  87107.  
  87108. /* Parm block for SetEntries control call */
  87109.  
  87110. æC 
  87111.  
  87112. æKY VDPageInfo
  87113. VDPgInfoPtr
  87114. æFc Video.h
  87115. æT struct
  87116. æD struct VDPageInfo {
  87117.     short csMode; /*(word) mode within device*/
  87118.     long csData; /*(long) data supplied by driver*/
  87119.     short csPage; /*(word) page to switch in*/
  87120.     Ptr csBaseAddr; /*(long) base address of page*/
  87121. };
  87122.  
  87123. typedef struct VDPageInfo VDPageInfo;
  87124. typedef VDPageInfo *VDPgInfoPtr;
  87125.  
  87126. æC 
  87127.  
  87128. æKY VDSizeInfo
  87129. VDSzInfoPtr
  87130. æFc Video.h
  87131. æT struct
  87132. æD struct VDSizeInfo {
  87133.     short csHSize; /*(word) desired/returned h size*/
  87134.     short csHPos; /*(word) desired/returned h position*/
  87135.     short csVSize; /*(word) desired/returned v size*/
  87136.     short csVPos; /*(word) desired/returned v position*/
  87137. };
  87138.  
  87139. typedef struct VDSizeInfo VDSizeInfo;
  87140. typedef VDSizeInfo *VDSzInfoPtr;
  87141.  
  87142. æC 
  87143.  
  87144. æKY VDSettings
  87145. VDSettingsPtr
  87146. æFc Video.h
  87147. æT struct
  87148. æD struct VDSettings {
  87149.     short csParamCnt; /*(word) number of params*/
  87150.     short csBrightMax; /*(word) max brightness*/
  87151.     short csBrightDef; /*(word) default brightness*/
  87152.     short csBrightVal; /*(word) current brightness*/
  87153.     short csCntrstMax; /*(word) max contrast*/
  87154.     short csCntrstDef; /*(word) default contrast*/
  87155.     short csCntrstVal; /*(word) current contrast*/
  87156.     short csTintMax; /*(word) max tint*/
  87157.     short csTintDef; /*(word) default tint*/
  87158.     short csTintVal; /*(word) current tint*/
  87159.     short csHueMax; /*(word) max hue*/
  87160.     short csHueDef; /*(word) default hue*/
  87161.     short csHueVal; /*(word) current hue*/
  87162.     short csHorizDef; /*(word) default horizontal*/
  87163.     short csHorizVal; /*(word) current horizontal*/
  87164.     short csHorizMax; /*(word) max horizontal*/
  87165.     short csVertDef; /*(word) default vertical*/
  87166.     short csVertVal; /*(word) current vertical*/
  87167.     short csVertMax; /*(word) max vertical*/
  87168. };
  87169.  
  87170. typedef struct VDSettings VDSettings;
  87171. typedef VDSettings *VDSettingsPtr;
  87172.  
  87173. æC 
  87174.  
  87175.  
  87176. æKY VMCalls.h
  87177. æKL DebuggerEnter
  87178. DebuggerExit
  87179. DebuggerGetMax
  87180. DebuggerLockMemory
  87181. DebuggerPoll
  87182. DebuggerUnlockMemory
  87183. DeferUserFn
  87184. EnterSupervisorMode
  87185. GetPageState
  87186. GetPhysical
  87187. HoldMemory
  87188. LockMemory
  87189. LockMemoryContiguous
  87190. PageFaultFatal
  87191. UnholdMemory
  87192. UnlockMemory
  87193.  
  87194. kNotPaged
  87195. kPageInMemory
  87196. kPageOnDisk
  87197. LogicalToPhysicalTable
  87198. MemoryBlock
  87199. notEnoughMemoryErr
  87200. PageState
  87201. StatusRegisterContents
  87202. _DebugUtil
  87203. _DeferUserFn
  87204. _MemoryDispatch
  87205.  
  87206. æKY kPageInMemory
  87207. æFc VMCalls.h
  87208. æT #define
  87209. æD 
  87210. /* values for PageState */
  87211.  
  87212. #define kPageInMemory 0
  87213. æC 
  87214.  
  87215. æKY kPageOnDisk
  87216. æFc VMCalls.h
  87217. æT #define
  87218. æD #define kPageOnDisk 1
  87219. æC 
  87220.  
  87221. æKY kNotPaged
  87222. æFc VMCalls.h
  87223. æT #define
  87224. æD #define kNotPaged 2
  87225. æC 
  87226.  
  87227. æKY _MemoryDispatch
  87228. æFc VMCalls.h
  87229. æT #define
  87230. æD 
  87231. /* trap number of MemoryDispatch */
  87232.  
  87233. #define _MemoryDispatch 0xA05C
  87234. æC 
  87235.  
  87236. æKY _DeferUserFn
  87237. æFc VMCalls.h
  87238. æT #define
  87239. æD 
  87240. /* trap number of DeferUserFn */
  87241.  
  87242. #define _DeferUserFn 0xA08F
  87243. æC 
  87244.  
  87245. æKY _DebugUtil
  87246. æFc VMCalls.h
  87247. æT #define
  87248. æD 
  87249. /* trap number of DebugUtil */
  87250.  
  87251. #define _DebugUtil 0xA08D
  87252. æC 
  87253.  
  87254. æKY notEnoughMemoryErr
  87255. æFc VMCalls.h
  87256. æT #define
  87257. æD 
  87258. /* error codes */
  87259.  
  87260. #define notEnoughMemoryErr -620 /* insufficient physical memory */
  87261. æC 
  87262.  
  87263. æKY PageState
  87264. æFc VMCalls.h
  87265. æT typedef
  87266. æD typedef short PageState;
  87267. æC 
  87268.  
  87269. æKY StatusRegisterContents
  87270. æFc VMCalls.h
  87271. æT typedef
  87272. æD typedef short StatusRegisterContents;
  87273. æC 
  87274.  
  87275. æKY MemoryBlock
  87276. æFc VMCalls.h
  87277. æT struct
  87278. æD struct MemoryBlock {
  87279.     void* address; /* start of block */
  87280.     unsigned long count; /* size of block */
  87281. };
  87282.  
  87283. typedef struct MemoryBlock MemoryBlock;
  87284. /*  data structures for VM calls  */
  87285. æC 
  87286.  
  87287. æKY LogicalToPhysicalTable
  87288. æFc VMCalls.h
  87289. æT struct
  87290. æD struct LogicalToPhysicalTable {
  87291.     MemoryBlock logical; /* logical block */
  87292.     MemoryBlock physical[defaultPhysicalEntryCount]; /* equivalent physical blocks */
  87293. };
  87294.  
  87295. typedef struct LogicalToPhysicalTable LogicalToPhysicalTable;
  87296. æC 
  87297.  
  87298. æKY HoldMemory
  87299. æFc VMCalls.h
  87300. æT Function
  87301. æD /*  keep pages in memory  */
  87302. pascal OSErr HoldMemory(void* address,unsigned long count); 
  87303. æDT /*  keep pages in memory  */
  87304. pascal OSErr myVariable = HoldMemory((void*) address,(unsigned long) count);
  87305. æRI VI
  87306. æC  
  87307. The HoldMemory function makes a portion of the address space resident in
  87308. physical memory and ineligible for paging.
  87309.  
  87310. The address parameter is the start address of the range of memory that is to be
  87311. held in RAM, and count is the size in bytes of that range. If the specified
  87312. address is not on a page boundary, it is rounded down to the nearest page
  87313. boundary. If the specified count is not an integral multiple of the system page
  87314. size, it is rounded up to the next whole multiple of page size.
  87315.  
  87316. Result codes
  87317. noErr                   0  No error
  87318. paramErr              –50  Error in parameter list
  87319. notEnoughMemoryErr   –620  Insufficient physical memory
  87320. interruptsMaskedErr  –624  Called with interrupts masked
  87321.  
  87322. æKY UnholdMemory
  87323. æFc VMCalls.h
  87324. æT Function
  87325. æD /*   allow pages to swap to backing store  */
  87326. pascal OSErr UnholdMemory(void* address,unsigned long count); 
  87327. æDT /*   allow pages to swap to backing store  */
  87328. pascal OSErr myVariable = UnholdMemory((void*) address,(unsigned long) count);
  87329. æRI VI
  87330. æC  
  87331. The UnholdMemory function makes a portion of the address space that is currently
  87332. held eligible for paging again. This function reverses the effects of
  87333. HoldMemory.
  87334.  
  87335. The address parameter is the start address of the range that is to be let go,
  87336. and count is the size in bytes of that range. If the specified address is not on
  87337. a page boundary, it is rounded down to the nearest page boundary. If the
  87338. specified count is not an integral multiple of the system page size, it is
  87339. rounded up to the next whole multiple of page size. 
  87340.  
  87341. Result codes
  87342. noErr                   0  No error
  87343. paramErr              -50  Error in parameter list
  87344. notHeldErr           –621  Specified range is not held
  87345. interruptsMaskedErr  –624  Called with interrupts masked
  87346.  
  87347. æKY LockMemory
  87348. æFc VMCalls.h
  87349. æT Function
  87350. æD /*   lock pages to physical memory  */
  87351. pascal OSErr LockMemory(void* address,unsigned long count); 
  87352. æDT /*   lock pages to physical memory  */
  87353. pascal OSErr myVariable = LockMemory((void*) address,(unsigned long) count);
  87354. æRI VI
  87355. æC  
  87356. The LockMemory function makes a portion of the address space immovable in
  87357. physical memory and ineligible for paging.
  87358.  
  87359. The address parameter is the start address of the range that is to be locked in
  87360. RAM, and count is the size in bytes of that range. If the specified address is
  87361. not on a page boundary, it is rounded down to the nearest page boundary. If the
  87362. specified count is not an integral multiple of the system page size, it is
  87363. rounded up to the next whole multiple of page size.
  87364.  
  87365. Result codes
  87366. noErr                   0  No error
  87367. paramErr              –50  Error in parameter list
  87368. notEnoughMemoryErr   –620  Insufficient physical memory
  87369. interruptsMaskedErr  –624  Called with interrupts masked 
  87370.  
  87371. æKY LockMemoryContiguous
  87372. æFc VMCalls.h
  87373. æT Function
  87374. æD /*  lock pages to contiguous physical memory  */
  87375. pascal OSErr LockMemoryContiguous(void* address,unsigned long count); 
  87376. æDT /*  lock pages to contiguous physical memory  */
  87377. pascal OSErr myVariable = LockMemoryContiguous((void*) address,(unsigned long) count);
  87378. æRI VI
  87379. æC  
  87380. The LockMemoryContiguous function is exactly like the LockMemory function,
  87381. except that it attempts to obtain a contiguous block of physical memory
  87382. associated with the logical address range specified.
  87383.  
  87384. The address parameter is the start address of the range that is to be locked in
  87385. RAM, and count is the size in bytes of that range. If the specified address is
  87386. not on a page boundary, it is rounded down to the nearest page boundary. If the
  87387. specified count is not an integral multiple of the system page size, it is
  87388. rounded up to the next whole multiple of page size.
  87389.  
  87390. Result codes
  87391. noErr                       0  No error
  87392. paramErr                  –50  Error in parameter list
  87393. notEnoughMemoryErr       –620  Insufficient physical memory
  87394. cannotMakeContiguousErr  –622  Cannot make specified range contiguous
  87395. interruptsMaskedErr      –624  Called with interrupts masked
  87396.  
  87397. æKY UnlockMemory
  87398. æFc VMCalls.h
  87399. æT Function
  87400. æD /*  allow pages to re-map to physical memory  */
  87401. pascal OSErr UnlockMemory(void* address,unsigned long count); 
  87402. æDT /*  allow pages to re-map to physical memory  */
  87403. pascal OSErr myVariable = UnlockMemory((void*) address,(unsigned long) count);
  87404. æRI VI
  87405. æC  
  87406. The UnlockMemory function makes a portion of the address space movable in real
  87407. memory and eligible for paging again.
  87408.  
  87409. The address parameter is the start address of the range that is to be unlocked,
  87410. and count is the size in bytes of that range. If the specified address is not on
  87411. a page boundary, it is rounded down to the nearest page boundary. If the
  87412. specified count is not an integral multiple of the system page size, it is
  87413. rounded up to the next whole multiple of page size.
  87414.  
  87415. Result codes
  87416. noErr                   0  No error
  87417. paramErr              –50  Error in parameter list
  87418. notEnoughMemoryErr   –620  Insufficient physical memory
  87419. notLockedErr         –623  Specified range is not locked
  87420. interruptsMaskedErr  –624  Called with interrupts masked
  87421.  
  87422. æKY GetPhysical
  87423. æFc VMCalls.h
  87424. æT Function
  87425. æD /*  map a logical block to physical blocks  */
  87426. pascal OSErr GetPhysical(LogicalToPhysicalTable* addresses,unsigned long* physicalEntryCount); 
  87427. æDT /*  map a logical block to physical blocks  */
  87428. pascal OSErr myVariable = GetPhysical((LogicalToPhysicalTable*) addresses,(unsigned long*) physicalEntryCount);
  87429. æRI VI
  87430. æC  
  87431. The GetPhysical function translates logical addresses into their corresponding
  87432. physical addresses.
  87433.  
  87434. The addresses parameter is the translation table and is an array of ordered
  87435. pairs (address and count). The physicalEntryCount parameter specifies the number
  87436. of physical entries to translate. GetPhysical translates up to the size of the
  87437. table or until the translation is completed, whichever comes first. If
  87438. GetPhysical is called with a table size of 0, the number of table entries needed
  87439. to translate the entire address range are returned. Upon exit from this
  87440. function, the virtual information is updated to indicate the next virtual
  87441. address and the number of bytes left to translate.
  87442.  
  87443. Result codes
  87444. noErr                   0  No error
  87445. paramErr              –50  Error in parameter list
  87446. notEnoughMemoryErr   –620  Insufficient physical memory
  87447. notLockedErr         –623  Specified range is not locked
  87448. interruptsMaskedErr  –624  Called with interrupts masked
  87449.  
  87450. æKY DeferUserFn
  87451. æFc VMCalls.h
  87452. æT Function
  87453. æD /*  delay execution of a procedure until page faulting is safe  */
  87454. pascal OSErr DeferUserFn(ProcPtr userFunc,void* argument); 
  87455. æDT /*  delay execution of a procedure until page faulting is safe  */
  87456. pascal OSErr myVariable = DeferUserFn((ProcPtr) userFunc,(void*) argument);
  87457. æRI VI
  87458. æC  
  87459. You can use the DeferUserFn function to determine whether code that might cause
  87460. page faults can safely be called immediately. If the code can be called safely,
  87461. then it is called. If a page fault is in progress, however, the routine address
  87462. and its parameter are saved and the routine is deferred until page faults are
  87463. again permitted.
  87464.  
  87465. You pass DeferUserFn the address of the routine that you want to run and a
  87466. pointer to the argument to pass to the specified routine.
  87467.  
  87468. Result codes
  87469. noErr              0  No error
  87470. cannotDeferErr  –625  Unable to defer additional user functions
  87471.  
  87472. The specified function is called with register A0 containing the value of the
  87473. argument parameter to the DeferUserFn call. Note that the routine can be called
  87474. immediately (before returning to the caller of DeferUserFn).
  87475.  
  87476. æKY DebuggerGetMax
  87477. æFc VMCalls.h
  87478. æT Function
  87479. æD 
  87480. /* 
  87481.      debugger support functions 
  87482.      return the highest function number supported 
  87483. */
  87484.  
  87485. pascal long DebuggerGetMax(void); 
  87486. æDT /* 
  87487.      debugger support functions 
  87488.      return the highest function number supported 
  87489. */
  87490.  
  87491. pascal long myVariable = DebuggerGetMax()(void);
  87492. æRI VI
  87493. æC  
  87494. The DebuggerGetMax function returns a long integer indicating the highest
  87495. function number supported by the DebugUtil trap.
  87496.  
  87497. The returned value is simply the selector number of the debugger functions that
  87498. are defined in terms of the DebugUtil trap. See “Debugger Support Under Virtual
  87499. Memory” earlier in this chapter for a complete list of these numbers.
  87500.  
  87501. æKY DebuggerEnter
  87502. æFc VMCalls.h
  87503. æT Function
  87504. æD /*  enter the debugging state  */
  87505. pascal void DebuggerEnter(void); 
  87506. æDT /*  enter the debugging state  */
  87507. pascal void myVariable = DebuggerEnter()(void);
  87508. æRI VI 
  87509. æC  
  87510. The two procedures DebuggerEnter and DebuggerExit allow you to enter and exit
  87511. the debugger state. These calls allow the DebugUtil trap to make preparations
  87512. for subsequent debugging calls and to clean up after all debugging calls are
  87513. completed.
  87514.  
  87515. PROCEDURE DebuggerEnter;
  87516. PROCEDURE DebuggerExit;
  87517.  
  87518. æKY DebuggerExit
  87519. æFc VMCalls.h
  87520. æT Function
  87521. æD /*  exit the debugging state  */
  87522. pascal void DebuggerExit(void); 
  87523. æDT /*  exit the debugging state  */
  87524. pascal void myVariable = DebuggerExit()(void);
  87525. æRI VI
  87526. æC  
  87527. The two procedures DebuggerEnter and DebuggerExit allow you to enter and exit
  87528. the debugger state. These calls allow the DebugUtil trap to make preparations
  87529. for subsequent debugging calls and to clean up after all debugging calls are
  87530. completed.
  87531.  
  87532. PROCEDURE DebuggerEnter;
  87533. PROCEDURE DebuggerExit;
  87534.  
  87535. æKY DebuggerPoll
  87536. æFc VMCalls.h
  87537. æT Function
  87538. æD /*  keyboard polling without interrupts  */
  87539. pascal long DebuggerPoll(void); 
  87540. æDT /*  keyboard polling without interrupts  */
  87541. pascal long myVariable = DebuggerPoll()(void);
  87542. æRI VI
  87543. æC  
  87544. A debugger can use the DebuggerPoll routine to poll for keyboard input.
  87545. This procedure can be used even if interrupts are disabled.
  87546.  
  87547. æKY GetPageState
  87548. æFc VMCalls.h
  87549. æT Function
  87550. æD /*  return the state of the page containing the address  */
  87551. pascal PageState GetPageState(void* address); 
  87552. æDT /*  return the state of the page containing the address  */
  87553. pascal PageState myVariable = GetPageState((void*) address);
  87554. æRI VI
  87555. æC  
  87556. The GetPageState function returns the state of a page of logical memory.
  87557.  
  87558. æKY PageFaultFatal
  87559. æFc VMCalls.h
  87560. æT Function
  87561. æD /*  determine if a page fault would currently be fatal  */
  87562. pascal Boolean PageFaultFatal(void); 
  87563. æDT /*  determine if a page fault would currently be fatal  */
  87564. pascal Boolean myVariable = PageFaultFatal()(void);
  87565. æRI VI
  87566. æC  
  87567. A debugger can use the PageFaultFatal function to determine whether it should
  87568. capture all bus errors, or whether it is safe to allow them to flow through to
  87569. virtual memory. When paging is safe, the debugger can allow virtual memory to
  87570. continue to service page faults, thus allowing the user to view all of memory.
  87571.  
  87572. If this function returns TRUE, then the debugger should not allow the virtual
  87573. memory bus error handler to detect any page faults.
  87574.  
  87575. æKY DebuggerLockMemory
  87576. æFc VMCalls.h
  87577. æT Function
  87578. æD /*  lock memory but do not disable cacheing of data  */
  87579. pascal OSErr DebuggerLockMemory(void* address,unsigned long count); 
  87580. æDT /*  lock memory but do not disable cacheing of data  */
  87581. pascal OSErr myVariable = DebuggerLockMemory((void*) address,(unsigned long) count);
  87582. æRI VI
  87583. æC  
  87584. The DebuggerLockMemory function does exactly what LockMemory does, except that
  87585. it leaves data caching enabled on the affected pages.
  87586.  
  87587.  
  87588. Result codes
  87589. noErr                  0  No error
  87590. paramErr             –50  Error in parameter list
  87591. notEnoughMemoryErr  –620  Insufficient physical memory
  87592.  
  87593.  
  87594. æKY DebuggerUnlockMemory
  87595. æFc VMCalls.h
  87596. æT Function
  87597. æD /*  undo the effects of DebuggerLockMemory  */
  87598. pascal OSErr DebuggerUnlockMemory(void* address,unsigned long count); 
  87599. æDT /*  undo the effects of DebuggerLockMemory  */
  87600. pascal OSErr myVariable = DebuggerUnlockMemory((void*) address,(unsigned long) count);
  87601. æRI VI
  87602. æC  
  87603. The DebuggerUnlockMemory function reverses the effects of DebuggerLockMemory.
  87604. Unlocking is applied to whole pages of the virtual address space. Unlocked pages
  87605. are marked as cacheable.
  87606.  
  87607. DebuggerUnlockMemory makes the portion of the address space starting with
  87608. address and continuing for count bytes movable in physical memory and eligible
  87609. for paging again.
  87610.  
  87611. Result codes
  87612. noErr            0  No error
  87613. paramErr       –50  Error in parameter list
  87614. notLockedErr  –623  Specified range is not locked
  87615.  
  87616. æKY EnterSupervisorMode
  87617. æFc VMCalls.h
  87618. æT Function
  87619. æD /*  explicitly enter supervisor mode  */
  87620. pascal StatusRegisterContents EnterSupervisorMode(void); 
  87621. æDT /*  explicitly enter supervisor mode  */
  87622. pascal StatusRegisterContents myVariable = EnterSupervisorMode()(void);
  87623. æRI VI
  87624. æC  
  87625. The EnterSupervisorMode function switches the caller into supervisor mode.
  87626.  
  87627. The return value, StatusRegisterContents, is an integer that holds the value of
  87628. the status register. You can use that value to restore the previous interrupt
  87629. level, condition codes, and so forth.
  87630.  
  87631.  
  87632. æKY Windows.h
  87633. æKL BeginUpdate
  87634. BringToFront
  87635. CalcVis
  87636. CalcVisBehind
  87637. CheckUpdate
  87638. ClipAbove
  87639. CloseWindow
  87640. DisposeWindow
  87641. draggrayrgn
  87642. DragGrayRgn
  87643. dragwindow
  87644. DragWindow
  87645. DrawGrowIcon
  87646. DrawNew
  87647. EndUpdate
  87648. FindWindow
  87649. findwindow
  87650. FrontWindow
  87651. GetAuxWin
  87652. GetCWMgrPort
  87653. GetGrayRgn
  87654. GetNewCWindow
  87655. GetNewWindow
  87656. GetWindowPic
  87657. GetWMgrPort
  87658. GetWRefCon
  87659. GetWTitle
  87660. getwtitle
  87661. GetWVariant
  87662. growwindow
  87663. GrowWindow
  87664. HideWindow
  87665. HiliteWindow
  87666. InitWindows
  87667. InvalRect
  87668. InvalRgn
  87669. MoveWindow
  87670. newcwindow
  87671. NewCWindow
  87672. NewWindow
  87673. newwindow
  87674. PaintBehind
  87675. PaintOne
  87676. PinRect
  87677. pinrect
  87678. SaveOld
  87679. SelectWindow
  87680. SendBehind
  87681. SetDeskCPat
  87682. SetWinColor
  87683. SetWindowPic
  87684. SetWRefCon
  87685. setwtitle
  87686. SetWTitle
  87687. ShowHide
  87688. ShowWindow
  87689. SizeWindow
  87690. TrackBox
  87691. trackbox
  87692. TrackGoAway
  87693. trackgoaway
  87694. ValidRect
  87695. ValidRgn
  87696. ZoomWindow
  87697.  
  87698. altDBoxProc
  87699. AuxWinHandle
  87700. AuxWinPtr
  87701. AuxWinRec
  87702. CWindowPeek
  87703. CWindowRecord
  87704. dBoxProc
  87705. deskPatID
  87706. dialogKind
  87707. documentProc
  87708. DragGrayRgnProcPtr
  87709. inContent
  87710. inDesk
  87711. inDrag
  87712. inGoAway
  87713. inGrow
  87714. inMenuBar
  87715. inSysWindow
  87716. inZoomIn
  87717. inZoomOut
  87718. noGrowDocProc
  87719. plainDBox
  87720. rDocProc
  87721. userKind
  87722. wCalcRgns
  87723. wContentColor
  87724. WCTabHandle
  87725. WCTabPtr
  87726. wDispose
  87727. wDraw
  87728. wDrawGIcon
  87729. wFrameColor
  87730. wGrow
  87731. wHiliteColor
  87732. wHit
  87733. wInContent
  87734. WinCTab
  87735. WindowPeek
  87736. WindowRecord
  87737. wInDrag
  87738. wInGoAway
  87739. wInGrow
  87740. wInZoomIn
  87741. wInZoomOut
  87742. wNew
  87743. wNoHit
  87744. WStateData
  87745. WStateDataHandle
  87746. WStateDataPtr
  87747. wTextColor
  87748. wTitleBarColor
  87749. zoomDocProc
  87750. zoomNoGrow
  87751.  
  87752. æKY documentProc
  87753. æFc Windows.h
  87754. æT #define
  87755. æD #define documentProc 0
  87756. æC 
  87757.  
  87758. æKY dBoxProc
  87759. æFc Windows.h
  87760. æT #define
  87761. æD #define dBoxProc 1
  87762. æC 
  87763.  
  87764. æKY plainDBox
  87765. æFc Windows.h
  87766. æT #define
  87767. æD #define plainDBox 2
  87768. æC 
  87769.  
  87770. æKY altDBoxProc
  87771. æFc Windows.h
  87772. æT #define
  87773. æD #define altDBoxProc 3
  87774. æC 
  87775.  
  87776. æKY noGrowDocProc
  87777. æFc Windows.h
  87778. æT #define
  87779. æD #define noGrowDocProc 4
  87780. æC 
  87781.  
  87782. æKY zoomDocProc
  87783. æFc Windows.h
  87784. æT #define
  87785. æD #define zoomDocProc 8
  87786. æC 
  87787.  
  87788. æKY zoomNoGrow
  87789. æFc Windows.h
  87790. æT #define
  87791. æD #define zoomNoGrow 12
  87792. æC 
  87793.  
  87794. æKY rDocProc
  87795. æFc Windows.h
  87796. æT #define
  87797. æD #define rDocProc 16
  87798. æC 
  87799.  
  87800. æKY dialogKind
  87801. æFc Windows.h
  87802. æT #define
  87803. æD #define dialogKind 2
  87804. æC 
  87805.  
  87806. æKY userKind
  87807. æFc Windows.h
  87808. æT #define
  87809. æD #define userKind 8
  87810. æC 
  87811.  
  87812. æKY inDesk
  87813. æFc Windows.h
  87814. æT #define
  87815. æD 
  87816. /* FindWindow Result Codes */
  87817.  
  87818. #define inDesk 0
  87819. æC 
  87820.  
  87821. æKY inMenuBar
  87822. æFc Windows.h
  87823. æT #define
  87824. æD #define inMenuBar 1
  87825. æC 
  87826.  
  87827. æKY inSysWindow
  87828. æFc Windows.h
  87829. æT #define
  87830. æD #define inSysWindow 2
  87831. æC 
  87832.  
  87833. æKY inContent
  87834. æFc Windows.h
  87835. æT #define
  87836. æD #define inContent 3
  87837. æC 
  87838.  
  87839. æKY inDrag
  87840. æFc Windows.h
  87841. æT #define
  87842. æD #define inDrag 4
  87843. æC 
  87844.  
  87845. æKY inGrow
  87846. æFc Windows.h
  87847. æT #define
  87848. æD #define inGrow 5
  87849. æC 
  87850.  
  87851. æKY inGoAway
  87852. æFc Windows.h
  87853. æT #define
  87854. æD #define inGoAway 6
  87855. æC 
  87856.  
  87857. æKY inZoomIn
  87858. æFc Windows.h
  87859. æT #define
  87860. æD #define inZoomIn 7
  87861. æC 
  87862.  
  87863. æKY inZoomOut
  87864. æFc Windows.h
  87865. æT #define
  87866. æD #define inZoomOut 8
  87867. æC 
  87868.  
  87869. æKY wDraw
  87870. æFc Windows.h
  87871. æT #define
  87872. æD 
  87873. /* window messages */
  87874.  
  87875. #define wDraw 0
  87876. æC 
  87877.  
  87878. æKY wHit
  87879. æFc Windows.h
  87880. æT #define
  87881. æD #define wHit 1
  87882. æC 
  87883.  
  87884. æKY wCalcRgns
  87885. æFc Windows.h
  87886. æT #define
  87887. æD #define wCalcRgns 2
  87888. æC 
  87889.  
  87890. æKY wNew
  87891. æFc Windows.h
  87892. æT #define
  87893. æD #define wNew 3
  87894. æC 
  87895.  
  87896. æKY wDispose
  87897. æFc Windows.h
  87898. æT #define
  87899. æD #define wDispose 4
  87900. æC 
  87901.  
  87902. æKY wGrow
  87903. æFc Windows.h
  87904. æT #define
  87905. æD #define wGrow 5
  87906. æC 
  87907.  
  87908. æKY wDrawGIcon
  87909. æFc Windows.h
  87910. æT #define
  87911. æD #define wDrawGIcon 6
  87912. æC 
  87913.  
  87914. æKY wNoHit
  87915. æFc Windows.h
  87916. æT #define
  87917. æD 
  87918. /* defProc hit test codes */
  87919.  
  87920. #define wNoHit 0
  87921. æC 
  87922.  
  87923. æKY wInContent
  87924. æFc Windows.h
  87925. æT #define
  87926. æD #define wInContent 1
  87927. æC 
  87928.  
  87929. æKY wInDrag
  87930. æFc Windows.h
  87931. æT #define
  87932. æD #define wInDrag 2
  87933. æC 
  87934.  
  87935. æKY wInGrow
  87936. æFc Windows.h
  87937. æT #define
  87938. æD #define wInGrow 3
  87939. æC 
  87940.  
  87941. æKY wInGoAway
  87942. æFc Windows.h
  87943. æT #define
  87944. æD #define wInGoAway 4
  87945. æC 
  87946.  
  87947. æKY wInZoomIn
  87948. æFc Windows.h
  87949. æT #define
  87950. æD #define wInZoomIn 5
  87951. æC 
  87952.  
  87953. æKY wInZoomOut
  87954. æFc Windows.h
  87955. æT #define
  87956. æD #define wInZoomOut 6
  87957. æC 
  87958.  
  87959. æKY deskPatID
  87960. æFc Windows.h
  87961. æT #define
  87962. æD #define deskPatID 16
  87963. æC 
  87964.  
  87965. æKY wContentColor
  87966. æFc Windows.h
  87967. æT #define
  87968. æD 
  87969. /* Window Part Identifiers which correlate color table entries with window elements */
  87970.  
  87971. #define wContentColor 0
  87972. æC 
  87973.  
  87974. æKY wFrameColor
  87975. æFc Windows.h
  87976. æT #define
  87977. æD #define wFrameColor 1
  87978. æC 
  87979.  
  87980. æKY wTextColor
  87981. æFc Windows.h
  87982. æT #define
  87983. æD #define wTextColor 2
  87984. æC 
  87985.  
  87986. æKY wHiliteColor
  87987. æFc Windows.h
  87988. æT #define
  87989. æD #define wHiliteColor 3
  87990. æC 
  87991.  
  87992. æKY wTitleBarColor
  87993. æFc Windows.h
  87994. æT #define
  87995. æD #define wTitleBarColor 4
  87996. æC 
  87997.  
  87998. æKY DragGrayRgnProcPtr
  87999. æFc Windows.h
  88000. æT typedef
  88001. æD typedef pascal void (*DragGrayRgnProcPtr)(void);
  88002. æC 
  88003.  
  88004. æKY WindowRecord
  88005. WindowPeek
  88006. æFc Windows.h
  88007. æT struct
  88008. æD struct WindowRecord {
  88009.     GrafPort port;
  88010.     short windowKind;
  88011.     Boolean visible;
  88012.     Boolean hilited;
  88013.     Boolean goAwayFlag;
  88014.     Boolean spareFlag;
  88015.     RgnHandle strucRgn;
  88016.     RgnHandle contRgn;
  88017.     RgnHandle updateRgn;
  88018.     Handle windowDefProc;
  88019.     Handle dataHandle;
  88020.     StringHandle titleHandle;
  88021.     short titleWidth;
  88022.     ControlHandle controlList;
  88023.     struct WindowRecord *nextWindow;
  88024.     PicHandle windowPic;
  88025.     long refCon;
  88026. };
  88027.  
  88028. typedef struct WindowRecord WindowRecord;
  88029. typedef WindowRecord *WindowPeek;
  88030.  
  88031. æC 
  88032.  
  88033. æKY CWindowRecord
  88034. CWindowPeek
  88035. æFc Windows.h
  88036. æT struct
  88037. æD struct CWindowRecord {
  88038.     CGrafPort port;
  88039.     short windowKind;
  88040.     Boolean visible;
  88041.     Boolean hilited;
  88042.     Boolean goAwayFlag;
  88043.     Boolean spareFlag;
  88044.     RgnHandle strucRgn;
  88045.     RgnHandle contRgn;
  88046.     RgnHandle updateRgn;
  88047.     Handle windowDefProc;
  88048.     Handle dataHandle;
  88049.     StringHandle titleHandle;
  88050.     short titleWidth;
  88051.     ControlHandle controlList;
  88052.     struct CWindowRecord *nextWindow;
  88053.     PicHandle windowPic;
  88054.     long refCon;
  88055. };
  88056.  
  88057. typedef struct CWindowRecord CWindowRecord;
  88058. typedef CWindowRecord *CWindowPeek;
  88059.  
  88060. æC 
  88061.  
  88062. æKY WStateData
  88063. WStateDataPtr
  88064. WStateDataHandle
  88065. æFc Windows.h
  88066. æT struct
  88067. æD struct WStateData {
  88068.     Rect userState; /*user state*/
  88069.     Rect stdState; /*standard state*/
  88070. };
  88071.  
  88072. typedef struct WStateData WStateData;
  88073. typedef WStateData *WStateDataPtr, **WStateDataHandle;
  88074.  
  88075. æC 
  88076.  
  88077. æKY AuxWinRec
  88078. AuxWinPtr
  88079. AuxWinHandle
  88080. æFc Windows.h
  88081. æT struct
  88082. æD struct AuxWinRec {
  88083.     struct AuxWinRec **awNext; /*handle to next AuxWinRec*/
  88084.     WindowPtr awOwner; /*ptr to window */
  88085.     CTabHandle awCTable; /*color table for this window*/
  88086.     Handle dialogCItem; /*handle to dialog manager structures*/
  88087.     long awFlags; /*reserved for expansion*/
  88088.     CTabHandle awReserved; /*reserved for expansion*/
  88089.     long awRefCon; /*user Constant*/
  88090. };
  88091.  
  88092. typedef struct AuxWinRec AuxWinRec;
  88093. typedef AuxWinRec *AuxWinPtr, **AuxWinHandle;
  88094.  
  88095. æC 
  88096.  
  88097. æKY WinCTab
  88098. WCTabPtr
  88099. WCTabHandle
  88100. æFc Windows.h
  88101. æT struct
  88102. æD struct WinCTab {
  88103.     long wCSeed; /*reserved*/
  88104.     short wCReserved; /*reserved*/
  88105.     short ctSize; /*usually 4 for windows*/
  88106.     ColorSpec ctTable[5];
  88107. };
  88108.  
  88109. typedef struct WinCTab WinCTab;
  88110. typedef WinCTab *WCTabPtr, **WCTabHandle;
  88111.  
  88112. æC 
  88113. _______________________________________________________________________________
  88114.  
  88115. »WINDOW COLOR TABLES
  88116. _______________________________________________________________________________
  88117.  
  88118. The contents and meaning of a window’s color table are determined by its window
  88119. definition function (see the “Defining Your Own Windows” section later in this chapter).
  88120. The CTabHandle parameter used in the Window Manager routines provides a handle to the
  88121. window color table. The color table containing the window’s colorSpecs can have any
  88122. number of entries, but standard window color tables as stored in the system resource
  88123. file have five colorSpecs.
  88124.  
  88125. The components of a window color table are defined as follows:
  88126.  
  88127. TYPE
  88128.   WCTabHandle = ^WCTabPtr;
  88129.   WCTabPtr    = ^WinCTab;
  88130.   WinCTab     = RECORD
  88131.                   wCSeed:      LONGINT;     {unique identifier from table}
  88132.                   wCReserved:  INTEGER;     {not used for windows}
  88133.                   ctSize:      INTEGER;     {number of entries in table –1}
  88134.                   ctTable:     Array [0..4] of ColorSpec;  {array of }
  88135.                                                            { ColorSpec records}
  88136.                 END;
  88137.  
  88138. Field descriptions
  88139.  
  88140. wCSeed        The wCSeed field is unused in window color tables, and is
  88141.               reserved for Apple’s use.
  88142. wCReserved    The wCReserved field is unused in window color tables, and is
  88143.               reserved for Apple’s use.
  88144. ctSize        The ctSize field defines the number of elements in the table,
  88145.               minus one. If your application is building a color table for
  88146.               use with the standard definition procedure, this field is always
  88147.               4. Custom window definition procedures can allocate color tables
  88148.               of any size.
  88149. ctTable       The ctTable field is made of an array of colorSpec records.
  88150.               Each colorSpec contains the partIdentifer and partRGB field,
  88151.               as shown below. The partIdentifier field holds an integer which
  88152.               associates a colorSpec to a particular part of the window. The
  88153.               definition procedures attempt to find the appropriate
  88154.               partIdentifier when preparing to draw a part. If that
  88155.               partIdentifier is not found, the first color in the table is
  88156.               used to draw the part. The partIdentifiers can appear in any
  88157.               order in the table. The partRGB field specifies a standard RGB
  88158.               color record, indicating what RGB value will be used to draw
  88159.               the window part found in partIdentifier.
  88160.  
  88161. The standard window type uses a five-element color table with part identifiers as
  88162. shown in Figure 6.
  88163.  
  88164.  
  88165. Figure 6–A Window Color Table
  88166.  
  88167. The following constants are used for the partIdentifiers in a window color table:
  88168.  
  88169.   wContentColor  =    0;
  88170.   wFrameColor    =    1;
  88171.   wTextColor     =    2;
  88172.   wHiliteColor   =    3;
  88173.   wTitleBarColor =    4;
  88174.  
  88175. The default color table read into the heap at application startup simply contains the
  88176. right combination of black and white to produce standard
  88177. black-and-white Macintosh windows. The last record in the auxiliary window list holds
  88178. a handle to this default color table. Before drawing a window, the standard window
  88179. definition function searches the list for an auxiliary record whose awOwner points to
  88180. the window to be drawn. If it finds such a record, it uses the color table designated
  88181. by that record; if it doesn’t find one before reaching the default record at the end
  88182. of the list, it uses the default color table instead. The default record is recognized
  88183. by NIL values in both its awNext and awOwner fields; your program must not change
  88184. these fields.
  88185.  
  88186. When creating a color window, the background color is set to the content color.
  88187. Old-style windows should use a content color of white.
  88188.  
  88189. A nonstandard window definition function can explicitly declare a color table of any
  88190. desired size and define its contents in any way it wishes, except that part identifiers
  88191. 1 to 127 are reserved for system definition. For compatibility with the defaulting
  88192. mechanism described above, the customized definition function should either use
  88193. indices 0 to 4 in the standard way, or else bypass the default by allocating an
  88194. explicit auxiliary record for every window it creates. To access a nonstandard window
  88195. color table from Pascal, the handle must be coerced to WCTabHandle.
  88196.  
  88197. The 'wctb' resource is an exact image of the window table data structure. This resource
  88198. is stored in a similar format as 'clut' color table resources. The partIdentifier and
  88199. partCode fields are stored as the colorSpec.value and colorSpec.RGBColor fields.
  88200.  
  88201. æKY InitWindows
  88202. æFc Windows.h
  88203. æT Function
  88204. æTN A912
  88205. æD 
  88206. pascal void InitWindows(void)
  88207.     = 0xA912; 
  88208. æDT 
  88209. InitWindows()(void);
  88210. æMM
  88211. æRT 53
  88212. æRI I-281, V-208, P-31, 78, 95, 101, 107, 112, 118, 175
  88213. æC  
  88214. »Initialization and Allocation
  88215.  
  88216. PROCEDURE InitWindows; [Macintosh Plus, Macintosh SE, Macintosh II]
  88217.  
  88218. InitWindows initializes the Window Manager. It creates the Window Manager port; you
  88219. can get a pointer to this port with the GetWMgrPort procedure. InitWindows draws the
  88220. desktop (as a rounded-corner rectangle with diameters of curvature 16,16, in the
  88221. desktop pattern) and the (empty) menu bar. Call this procedure once before all other
  88222. Window Manager routines.
  88223.  
  88224. Note:  The desktop pattern is the pattern whose resource ID is:
  88225.  
  88226.          CONST deskPatID = 16;
  88227.  
  88228.        If you store a pattern with resource ID deskPatID in the application’s
  88229.        resource file, that pattern will be used whenever the desktop is drawn.
  88230.  
  88231. The InitWindow procedure now calls the new Menu Bar definition procedure to calculate
  88232. menu bar height, and to draw the empty menu bar. Since the menu bar definition procedure
  88233. ('MBDF') actually performs these calculations, InitWindows now calls InitMenus directly.
  88234. InitMenus has been modified so that it can be called twice in a program without ill
  88235. effect.
  88236.  
  88237. For the Macintosh II, if the color desktop pattern is enabled, InitWindows loads the
  88238. default desktop pixel pattern as well as the standard binary pattern. It allocates
  88239. both the WMgrCPort and the WMgrPort, then calculates the union of all active screen
  88240. devices, and saves this region in the global variable GrayRgn.
  88241.  
  88242. Warning:  InitWindows creates the Window Manager port as a nonrelocatable
  88243.           block in the application heap. To prevent heap fragmentation,
  88244.           call InitWindows in the main segment of your program, before any
  88245.           references to routines in other segments.
  88246.  
  88247. Assembly-language note:  InitWindows initializes the global variable GrayRgn
  88248.                          to be a handle to the desktop region (a rounded-corner
  88249.                          rectangle occupying the entire screen, minus the menu
  88250.                          bar), and draws this region. It initializes the global
  88251.                          variable DeskPattern to the pattern whose resource ID
  88252.                          is deskPatID, and paints the desktop with this pattern.
  88253.                          Any subsequent time that the desktop needs to be drawn,
  88254.                          such as when a new area of it is exposed after a
  88255.                          window is closed or moved, the Window Manager calls
  88256.                          the procedure pointed to by the global variable
  88257.                          DeskHook, if any (normally DeskHook is 0). The
  88258.                          DeskHook procedure is called with 0 in register D0
  88259.                          to distinguish this use of it from its use in
  88260.                          responding to clicks on the desktop (discussed in the
  88261.                          description of FindWindow); it should respond by
  88262.                          painting thePort^.clipRgn with DeskPattern and then
  88263.                          doing anything else it wants.
  88264.  
  88265. æKY GetWMgrPort
  88266. æFc Windows.h
  88267. æT Function
  88268. æTN A910
  88269. æD pascal void GetWMgrPort(GrafPtr *wPort)
  88270.     = 0xA910; 
  88271. æDT GetWMgrPort((GrafPtr *) wPort);
  88272. æRT 194
  88273. æRI I-282
  88274. æC  
  88275. GetWMgrPort returns in wPort a pointer to the Window Manager port.
  88276.  
  88277. Warning:  Do not change any regions of the Window Manager port, or
  88278.           overlapping windows may not be handled properly.
  88279.  
  88280. Assembly-language note:  This pointer is stored in the global variable
  88281.                          WMgrPort.
  88282.  
  88283. æKY NewWindow
  88284. æFc Windows.h
  88285. æT Function
  88286. æTN A913
  88287. æD pascal WindowPtr NewWindow(Ptr wStorage,const Rect *boundsRect,const Str255 title,
  88288.     Boolean visible,short theProc,WindowPtr behind,Boolean goAwayFlag,long refCon)
  88289.     = 0xA913; 
  88290. æDT WindowPtr myVariable = NewWindow((Ptr) wStorage,(const Rect *) boundsRect,(const Str255) title,()
  88291.     Boolean visible,(short) theProc,(WindowPtr) behind,(Boolean) goAwayFlag,(long) refCon);
  88292. æMM
  88293. æRI I-282, P-95, 178
  88294. æC  
  88295. NewWindow creates a window as specified by its parameters, adds it to the window
  88296. list, and returns a windowPtr to the new window. It allocates space for the structure
  88297. and content regions of the window and asks the window definition function to calculate
  88298. those regions.
  88299.  
  88300. WStorage is a pointer to where to store the window record. For example, if
  88301. you’ve declared the variable wRecord of type WindowRecord, you can pass @wRecord as
  88302. the first parameter to NewWindow. If you pass NIL for wStorage, the window record
  88303. will be allocated as a nonrelocatable object in the heap; in that case, though, you
  88304. risk ending up with a fragmented heap.
  88305.  
  88306. BoundsRect, a rectangle given in global coordinates, determines the window’s size and
  88307. location, and becomes the portRect of the window’s grafPort; note, however, that the
  88308. portRect is in local coordinates. NewWindow sets the top left corner of the portRect
  88309. to (0,0). For the standard types of windows, the boundsRect defines the content
  88310. region of the window.
  88311.  
  88312. Note:  The bit map, pen pattern, and other characteristics of the window’s
  88313.        grafPort are the same as the default values set by the OpenPort
  88314.        procedure in QuickDraw, except for the character font, which is set
  88315.        to the application font rather than the system font. (NewWindow
  88316.        actually calls OpenPort to initialize the window’s grafPort.) Note,
  88317.        however, that the coordinates of the grafPort’s portBits.bounds and
  88318.        visRgn are changed along with its portRect.
  88319.  
  88320. The title parameter is the window’s title. If the title of a document window is
  88321. longer than will fit in the title bar, it’s truncated in one of two ways:  If the
  88322. window has a close box, the characters that don’t fit are truncated from the end of
  88323. the title; if there’s no close box, the title is centered and truncated at both
  88324. ends.
  88325.  
  88326. If the visible parameter is TRUE, NewWindow draws the window. First it calls the
  88327. window definition function to draw the window frame; if goAwayFlag is also TRUE and
  88328. the window is frontmost (as specified by the behind parameter, below), it draws a
  88329. go-away region in the frame. Then it generates an update event for the entire window
  88330. contents.
  88331.  
  88332. ProcID is the window definition ID, which leads to the window definition function for
  88333. this type of window. The function is read into memory if it’s not already in memory.
  88334. If it can’t be read, NewWindow returns NIL. The window definition IDs for the standard
  88335. types of windows are listed above under
  88336. “Windows and Resources”. Window definition IDs for windows of your own design are
  88337. discussed later under “Defining Your Own Windows”.
  88338.  
  88339. The behind parameter determines the window’s plane. The new window is inserted in
  88340. back of the window pointed to by this parameter. To put the new window behind all
  88341. other windows, use behind=NIL. To place it in front of all other windows, use behind=POINTER(–1);
  88342. in this case, NewWindow will unhighlight the previously active window, highlight the
  88343. window being created, and generate appropriate activate events.
  88344.  
  88345. RefCon is the window’s reference value, set and used only by your application.
  88346.  
  88347. NewWindow also sets the window class in the window record to indicate that the window
  88348. was created directly by the application.
  88349.  
  88350. æKY GetNewWindow
  88351. æFc Windows.h
  88352. æT Function
  88353. æTN A9BD
  88354. æD pascal WindowPtr GetNewWindow(short windowID,Ptr wStorage,WindowPtr behind)
  88355.     = 0xA9BD; 
  88356. æDT WindowPtr myVariable = GetNewWindow((short) windowID,(Ptr) wStorage,(WindowPtr) behind);
  88357. æMM
  88358. æRT 4
  88359. æRI I-283, P-95, 173
  88360. æC  
  88361. Like NewWindow (above), GetNewWindow creates a window as specified by its parameters,
  88362. adds it to the window list, and returns a windowPtr to the new window. The only
  88363. difference between the two functions is that instead of having the parameters boundsRect,
  88364. title, visible, procID, goAwayFlag, and refCon, GetNewWindow has a single windowID
  88365. parameter, where windowID is the resource ID of a window template that supplies the
  88366. same information as those parameters. If the window template can’t be read from the
  88367. resource file, GetNewWindow returns NIL. GetNewWindow releases the memory occupied by
  88368. the resource before returning. The wStorage and behind parameters have the same
  88369. meaning as in NewWindow.
  88370.  
  88371. æKY CloseWindow
  88372. æFc Windows.h
  88373. æT Function
  88374. æTN A92D
  88375. æD pascal void CloseWindow(WindowPtr theWindow)
  88376.     = 0xA92D; 
  88377. æDT CloseWindow((WindowPtr) theWindow);
  88378. æMM
  88379. æRI I-283, P-96, 98, 167
  88380. æC  
  88381. CloseWindow removes the given window from the screen and deletes it from the window
  88382. list. It releases the memory occupied by all data structures associated with the
  88383. window, but not the memory taken up by the window record itself. Call this procedure
  88384. when you’re done with a window if you supplied NewWindow or GetNewWindow a pointer to
  88385. the window storage (in the wStorage parameter) when you created the window.
  88386.  
  88387. Any update events for the window are discarded. If the window was the frontmost
  88388. window and there was another window behind it, the latter window is highlighted and
  88389. an appropriate activate event is generated.
  88390.  
  88391. Warning:  If you allocated memory yourself and stored a handle to it in the
  88392.           refCon field, CloseWindow won’t know about it—you must release the
  88393.           memory before calling CloseWindow. Similarly, if you used the
  88394.           windowPic field to access a picture stored as a resource, you must
  88395.           release the memory it occupies; CloseWindow assumes the picture
  88396.           isn’t a resource, and calls the QuickDraw procedure KillPicture to
  88397.           delete it.
  88398.  
  88399. æKY DisposeWindow
  88400. æFc Windows.h
  88401. æT Function
  88402. æTN A914
  88403. æD pascal void DisposeWindow(WindowPtr theWindow)
  88404.     = 0xA914; 
  88405. æDT DisposeWindow((WindowPtr) theWindow);
  88406. æRI I-284, P-96, 98, 168
  88407. æC 
  88408. Assembly-language note:  The macro you invoke to call DisposeWindow from
  88409.                          assembly language is named _DisposWindow.
  88410.  
  88411. Dispose Window calls CloseWindow (above) and then releases the memory occupied by the
  88412. window record. Call this procedure when you’re done with a window if you let the
  88413. window record be allocated in the heap when you created the window (by passing NIL as
  88414. the wStorage parameter to NewWindow or GetNewWindow).
  88415.  
  88416. æKY setwtitle
  88417. æFc Windows.h
  88418. æT Function
  88419. æD void setwtitle(WindowPtr theWindow,char *title); 
  88420. æDT setwtitle((WindowPtr) theWindow,(char *) title);
  88421. æMM
  88422. æRI I-284
  88423. æC  
  88424. SetWTitle sets theWindow’s title to the given string, performing any necessary redrawing
  88425. of the window frame.
  88426.  
  88427. æKY GetWTitle
  88428. æFc Windows.h
  88429. æT Function
  88430. æTN A919
  88431. æD pascal void GetWTitle(WindowPtr theWindow,Str255 title)
  88432.     = 0xA919; 
  88433. æDT GetWTitle((WindowPtr) theWindow,(Str255) title);
  88434. æRI I-284
  88435. æC  
  88436. GetWTitle returns theWindow's title as the value of the title parameter.
  88437.  
  88438. æKY SelectWindow
  88439. æFc Windows.h
  88440. æT Function
  88441. æTN A91F
  88442. æD pascal void SelectWindow(WindowPtr theWindow)
  88443.     = 0xA91F; 
  88444. æDT SelectWindow((WindowPtr) theWindow);
  88445. æMM
  88446. æRT 205
  88447. æRI I-284, P-37, 98, 179
  88448. æC  
  88449. SelectWindow makes theWindow the active window as follows:  It unhighlights the
  88450. previously active window, brings theWindow in front of all other windows, highlights
  88451. theWindow, and generates the appropriate activate events. Call this procedure if
  88452. there’s a mouse-down event in the content region of an inactive window.
  88453.  
  88454. æKY HideWindow
  88455. æFc Windows.h
  88456. æT Function
  88457. æTN A916
  88458. æD pascal void HideWindow(WindowPtr theWindow)
  88459.     = 0xA916; 
  88460. æDT HideWindow((WindowPtr) theWindow);
  88461. æMM
  88462. æRI I-285
  88463. æC 
  88464. HideWindow makes theWindow invisible. If theWindow is the frontmost window and there’s
  88465. a window behind it, HideWindow also unhighlights theWindow, brings the window behind
  88466. it to the front, highlights that window, and generates appropriate activate events
  88467. (see Figure 8). If theWindow is already invisible, HideWindow has no effect.
  88468.  
  88469. æKY ShowWindow
  88470. æFc Windows.h
  88471. æT Function
  88472. æTN A915
  88473. æD pascal void ShowWindow(WindowPtr theWindow)
  88474.     = 0xA915; 
  88475. æDT ShowWindow((WindowPtr) theWindow);
  88476. æMM
  88477. æRI I-285
  88478. æC  
  88479. ShowWindow makes theWindow visible. It does not change the front-to-back ordering of
  88480. the windows. Remember that if you previously hid the frontmost window with HideWindow,
  88481. HideWindow will have brought the window behind it to the front; so if you then do a
  88482. ShowWindow of the window you hid, it will no longer be frontmost (see Figure 8). If
  88483. theWindow is already visible, ShowWindow has no effect.
  88484.  
  88485. Note:  Although it’s inadvisable, you can create a situation where the
  88486.        frontmost window is invisible. If you do a ShowWindow of such a
  88487.        window, it will highlight the window if it’s not already highlighted
  88488.        and will generate an activate event to force this window from inactive
  88489.        to active.
  88490.  
  88491. æKY ShowHide
  88492. æFc Windows.h
  88493. æT Function
  88494. æTN A908
  88495. æD pascal void ShowHide(WindowPtr theWindow,Boolean showFlag)
  88496.     = 0xA908; 
  88497. æDT ShowHide((WindowPtr) theWindow,(Boolean) showFlag);
  88498. æMM
  88499. æRI I-285
  88500. æC  
  88501. If showFlag is TRUE, ShowHide makes theWindow visible if it’s not already visible and
  88502. has no effect if it is already visible. If showFlag is FALSE, ShowHide makes theWindow
  88503. invisible if it’s not already invisible and has no effect if it is already invisible.
  88504. Unlike HideWindow and ShowWindow, ShowHide never changes the highlighting or front-to-back
  88505. ordering of windows or generates activate events.
  88506.  
  88507. Warning:  Use this procedure carefully, and only in special circumstances
  88508.           where you need more control than allowed by HideWindow and
  88509.           ShowWindow.
  88510.  
  88511. æKY HiliteWindow
  88512. æFc Windows.h
  88513. æT Function
  88514. æTN A91C
  88515. æD pascal void HiliteWindow(WindowPtr theWindow,Boolean fHilite)
  88516.     = 0xA91C; 
  88517. æDT HiliteWindow((WindowPtr) theWindow,(Boolean) fHilite);
  88518. æMM
  88519. æRI I-286
  88520. æC  
  88521. If fHilite is TRUE, this procedure highlights theWindow if it’s not already highlighted
  88522. and has no effect if it is highlighted. If fHilite is FALSE, HiliteWindow unhighlights
  88523. theWindow if it is highlighted and has no effect if it’s not highlighted. The exact
  88524. way a window is highlighted depends on its window definition function.
  88525.  
  88526. Normally you won’t have to call this procedure, since you should call SelectWindow to
  88527. make a window active, and SelectWindow takes care of the necessary highlighting
  88528. changes. Highlighting a window that isn’t the active window is contrary to the Macintosh
  88529. User Interface Guidelines.
  88530.  
  88531. æKY BringToFront
  88532. æFc Windows.h
  88533. æT Function
  88534. æTN A920
  88535. æD pascal void BringToFront(WindowPtr theWindow)
  88536.     = 0xA920; 
  88537. æDT BringToFront((WindowPtr) theWindow);
  88538. æMM
  88539. æRI I-286
  88540. æC  
  88541. BringToFront brings theWindow to the front of all other windows and redraws the
  88542. window as necessary. Normally you won’t have to call this procedure, since you should
  88543. call SelectWindow to make a window active, and SelectWindow takes care of bringing
  88544. the window to the front. If you do call BringToFront, however, remember to call
  88545. HiliteWindow to make the necessary highlighting changes.
  88546.  
  88547. æKY SendBehind
  88548. æFc Windows.h
  88549. æT Function
  88550. æTN A921
  88551. æD pascal void SendBehind(WindowPtr theWindow,WindowPtr behindWindow)
  88552.     = 0xA921; 
  88553. æDT SendBehind((WindowPtr) theWindow,(WindowPtr) behindWindow);
  88554. æMM
  88555. æRI I-286
  88556. æC  
  88557. SendBehind sends theWindow behind behindWindow, redrawing any exposed windows. If
  88558. behindWindow is NIL, it sends theWindow behind all other windows. If theWindow is the
  88559. active window, it unhighlights theWindow, highlights the new active window, and
  88560. generates the appropriate activate events.
  88561.  
  88562. Warning:  Do not use SendBehind to deactivate a previously active window.
  88563.           Calling SelectWindow to make a window active takes care of
  88564.           deactivating the previously active window.
  88565.  
  88566. Note:  If you’re moving theWindow closer to the front (that is, if it’s
  88567.        initially even farther behind behindWindow), you must make the
  88568.        following calls after calling SendBehind:
  88569.  
  88570.          wPeek := POINTER(theWindow);
  88571.          PaintOne(wPeek, wPeek^.strucRgn);
  88572.          CalcVis(wPeek)
  88573.  
  88574.        PaintOne and CalcVis are described under “Low-Level Routines”.
  88575.  
  88576. æKY FrontWindow
  88577. æFc Windows.h
  88578. æT Function
  88579. æTN A924
  88580. æD pascal WindowPtr FrontWindow(void)
  88581.     = 0xA924; 
  88582. æDT WindowPtr myVariable = FrontWindow()(void);
  88583. æRI I-286
  88584. æC  
  88585. FrontWindow returns a pointer to the first visible window in the window list
  88586. (that is, the active window). If there are no visible windows, it returns NIL.
  88587.  
  88588. Assembly-language note:  In the global variable GhostWindow, you can store
  88589.                          a pointer to a window that’s not to be considered
  88590.                          frontmost even if it is (for example, if you want
  88591.                          to have a special editing window always present
  88592.                          and floating above all the others). If the window
  88593.                          pointed to by GhostWindow is the first window in
  88594.                          the window list, FrontWindow will return a pointer
  88595.                          to the next visible window.
  88596.  
  88597. æKY DrawGrowIcon
  88598. æFc Windows.h
  88599. æT Function
  88600. æTN A904
  88601. æD pascal void DrawGrowIcon(WindowPtr theWindow)
  88602.     = 0xA904; 
  88603. æDT DrawGrowIcon((WindowPtr) theWindow);
  88604. æMM
  88605. æRI I-287, P-169
  88606. æC  
  88607. Call DrawGrowIcon in response to an update or activate event involving a window that
  88608. contains a size box in its content region. If theWindow is active, DrawGrowIcon draws
  88609. the size box; otherwise, it draws whatever is appropriate to show that the window
  88610. temporarily cannot be sized. The exact appearance and location of what’s drawn depend
  88611. on the window definition function. For an active document window, DrawGrowIcon draws
  88612. the size box icon in the bottom right corner of the portRect of the window’s grafPort,
  88613. along with the lines delimiting the size box and scroll bar areas (15 pixels in from
  88614. the right edge and bottom of the portRect). It doesn’t erase the scroll bar areas, so
  88615. if the window doesn’t contain scroll bars you should erase those areas yourself after
  88616. the window’s size changes. For an inactive document window, DrawGrowIcon draws only
  88617. the lines delimiting the size box and scroll bar areas, and erases the size box
  88618. icon.
  88619.  
  88620. æKY MoveWindow
  88621. æFc Windows.h
  88622. æT Function
  88623. æTN A91B
  88624. æD pascal void MoveWindow(WindowPtr theWindow,short hGlobal,short vGlobal,
  88625.     Boolean front)
  88626.     = 0xA91B; 
  88627. æDT MoveWindow((WindowPtr) theWindow,(short) hGlobal,(short) vGlobal,()
  88628.     Boolean front);
  88629. æMM
  88630. æRI I-289, V-209, P-177
  88631. æC 
  88632. [Macintosh II]
  88633.  
  88634. MoveWindow moves theWindow to another part of the screen, without affecting its size
  88635. or plane. The top left corner of the portRect of the window’s grafPort is moved to
  88636. the screen point indicated by the global coordinates hGlobal and vGlobal. The local
  88637. coordinates of the top left corner remain the same. If the front parameter is TRUE
  88638. and theWindow isn’t the active window, MoveWindow makes it the active window by
  88639. calling SelectWindow(theWindow).
  88640.  
  88641. The MoveWindow routine formerly copied a window’s entire structure region. On multiple-screen
  88642. systems, MoveWindow now copies only the portion of the window that will remain on the
  88643. same screen. All other parts of the window are not copied, and are redrawn on the
  88644. next update event. When a window’s content crosses screen boundaries, MoveWindow may
  88645. post additional updates on multiple screen systems.
  88646.  
  88647. æKY SizeWindow
  88648. æFc Windows.h
  88649. æT Function
  88650. æTN A91D
  88651. æD pascal void SizeWindow(WindowPtr theWindow,short w,short h,Boolean fUpdate)
  88652.     = 0xA91D; 
  88653. æDT SizeWindow((WindowPtr) theWindow,(short) w,(short) h,(Boolean) fUpdate);
  88654. æMM
  88655. æRI I-290, P-98, 181
  88656. æC  
  88657. SizeWindow enlarges or shrinks the portRect of theWindow’s grafPort to the width and
  88658. height specified by w and h, or does nothing if w and h are 0. The window’s position
  88659. on the screen does not change. The new window frame is drawn; if the width of a
  88660. document window changes, the title is again centered in the title bar, or is truncated
  88661. if it no longer fits. If fUpdate is TRUE, SizeWindow accumulates any newly created
  88662. area of the content region into the update region (see Figure 11); normally this is
  88663. what you’ll want. If you pass FALSE for fUpdate, you’re responsible for the update
  88664. region maintenance yourself. For more information, see InvalRect and ValidRect.
  88665.  
  88666. •••Refer to Figure 11.•••
  88667.  
  88668. Figure 11–SizeWindow Operation on a Document Window
  88669.  
  88670. æKY ZoomWindow
  88671. æFc Windows.h
  88672. æT Function
  88673. æTN A83A
  88674. æD pascal void ZoomWindow(WindowPtr theWindow,short partCode,Boolean front)
  88675.     = 0xA83A; 
  88676. æDT ZoomWindow((WindowPtr) theWindow,(short) partCode,(Boolean) front);
  88677. æMM
  88678. æRT 79
  88679. æRI IV-50, V-210
  88680. æC  
  88681. Call ZoomWindow after a call to TrackBox that returns TRUE. The partCode parameter
  88682. contains the constant (either inZoomIn or inZoomOut) returned by FindWindow. The
  88683. window will be zoomed either out or in, depending on the state of the window specified
  88684. by partCode. If the window is already in the state specified by partCode, ZoomWindow
  88685. does nothing. If the front parameter is TRUE, the window will be brought to the
  88686. front; otherwise, the window is left where it is. (This means a window can be zoomed
  88687. without necessarily becoming the active window.)
  88688.  
  88689. On multiple-screen systems, applications that call ZoomWindow with a new size based
  88690. on the screen rectangle (screenBits.bounds) will now cause any windows not on the
  88691. main screen to zoom to full size on the main screen. To perform properly in a multiscreen
  88692. environment, these applications should test which screen contains the greatest area
  88693. of the window to be zoomed, and then zoom to the screen rectangle (GDRect) for that
  88694. screen device. See the Graphics Devices chapter for information on obtaining the
  88695. GDRect value for a device.
  88696.  
  88697. For best results, call the QuickDraw procedure EraseRect with the portRect field of
  88698. theWindow’s grafPort before calling ZoomWindow.
  88699.  
  88700. Warning:  Using the QuickDraw procedure SetPort, set thePort to the window’s
  88701.           port before calling ZoomWindow.
  88702.  
  88703. Note:  ZoomWindow is in no way tied to the TrackBox function and could just
  88704.        as easily be called in response to a selection from a menu.
  88705.  
  88706. æKY InvalRect
  88707. æFc Windows.h
  88708. æT Function
  88709. æTN A928
  88710. æD pascal void InvalRect(const Rect *badRect)
  88711.     = 0xA928; 
  88712. æDT InvalRect((const Rect *) badRect);
  88713. æMM
  88714. æRI I-291
  88715. æC  
  88716. InvalRect accumulates the given rectangle into the update region of the window whose
  88717. grafPort is the current port. This tells the Window Manager that the rectangle has
  88718. changed and must be updated. The rectangle is given in local coordinates and is
  88719. clipped to the window’s content region.
  88720.  
  88721. For example, this procedure is useful when you’re calling SizeWindow for a document
  88722. window that contains a size box or scroll bars. Suppose you’re going to call SizeWindow
  88723. with fUpdate=TRUE. If the window is enlarged as shown in Figure 10, you’ll want not
  88724. only the newly created part of the content region to be updated, but also the two
  88725. rectangular areas containing the (former) size box and scroll bars; before calling
  88726. SizeWindow, you can call InvalRect twice to accumulate those areas into the update
  88727. region. In case the window is made smaller, you’ll want the new size box and scroll
  88728. bar areas to be updated, and so can similarly call InvalRect for those areas after
  88729. calling SizeWindow. See Figure 12 for an illustration of this type of update region
  88730. maintenance.
  88731.  
  88732. As another example, suppose your application scrolls up text in a document window and
  88733. wants to show new text added at the bottom of the window. You can cause the added
  88734. text to be redrawn by accumulating that area into the update region with InvalRect.
  88735.  
  88736. PROCEDURE InvalRgn (badRgn:  RgnHandle);
  88737.  
  88738. InvalRgn is the same as InvalRect but for a region that has changed rather than a
  88739. rectangle.
  88740.  
  88741. •••Refer to Figure 12.•••
  88742.  
  88743. Figure 12–Update Region Maintenance with InvalRect
  88744.  
  88745. æKY InvalRgn
  88746. æFc Windows.h
  88747. æT Function
  88748. æTN A927
  88749. æD pascal void InvalRgn(RgnHandle badRgn)
  88750.     = 0xA927; 
  88751. æDT InvalRgn((RgnHandle) badRgn);
  88752. æMM
  88753. æRI I-291
  88754. æC     InvalRgn is the same as InvalRect (above) but for a region that has
  88755. changed rather than a rectangle.
  88756.  
  88757. æKY ValidRect
  88758. æFc Windows.h
  88759. æT Function
  88760. æTN A92A
  88761. æD pascal void ValidRect(const Rect *goodRect)
  88762.     = 0xA92A; 
  88763. æDT ValidRect((const Rect *) goodRect);
  88764. æMM
  88765. æRI I-292
  88766. æC  
  88767. ValidRect removes goodRect from the update region of the window whose grafPort is the
  88768. current port. This tells the Window Manager that the application has already drawn
  88769. the rectangle and to cancel any updates accumulated for that area. The rectangle is
  88770. clipped to the window’s content region and is given in local coordinates. Using
  88771. ValidRect results in better performance and less redundant redrawing in the window.
  88772.  
  88773. For example, suppose you’ve called SizeWindow with fUpdate=TRUE for a document window
  88774. that contains a size box or scroll bars. Depending on the dimensions of the newly
  88775. sized window, the new size box and scroll bar areas may or may not have been accumulated
  88776. into the window’s update region. After calling SizeWindow, you can redraw the size
  88777. box or scroll bars immediately and then call ValidRect for the areas they occupy in
  88778. case they were in fact accumulated into the update region; this will avoid redundant
  88779. drawing.
  88780.  
  88781. æKY ValidRgn
  88782. æFc Windows.h
  88783. æT Function
  88784. æTN A929
  88785. æD pascal void ValidRgn(RgnHandle goodRgn)
  88786.     = 0xA929; 
  88787. æDT ValidRgn((RgnHandle) goodRgn);
  88788. æMM
  88789. æRI I-292
  88790. æC  
  88791. ValidRgn is the same as ValidRect but for a region that has been drawn rather than a
  88792. rectangle.
  88793.  
  88794. æKY BeginUpdate
  88795. æFc Windows.h
  88796. æT Function
  88797. æTN A922
  88798. æD pascal void BeginUpdate(WindowPtr theWindow)
  88799.     = 0xA922; 
  88800. æDT BeginUpdate((WindowPtr) theWindow);
  88801. æMM
  88802. æRI I-292, P-97, 167
  88803. æC 
  88804. Call BeginUpdate when an update event occurs for theWindow. BeginUpdate replaces the
  88805. visRgn of the window’s grafPort with the intersection of the visRgn and the update
  88806. region and then sets the window’s update region to an empty region. You would then
  88807. usually draw the entire content region, though it suffices to draw only the visRgn;
  88808. in either case, only the parts of the window that require updating will actually be
  88809. drawn on the screen. Every call to BeginUpdate must be balanced by a call to EndUpdate.
  88810. (See “How a Window is Drawn”.)
  88811.  
  88812. Note:  In Pascal, BeginUpdate and EndUpdate calls can’t be nested (that is,
  88813.        you must call EndUpdate before the next call to BeginUpdate).
  88814.  
  88815. Assembly-language note:  A handle to a copy of the original visRgn (in
  88816.                          global coordinates) is stored in the global
  88817.                          variable SaveVisRgn. You can nest BeginUpdate and
  88818.                          EndUpdate calls in assembly language if you save
  88819.                          and restore this region.
  88820.  
  88821. æKY EndUpdate
  88822. æFc Windows.h
  88823. æT Function
  88824. æTN A923
  88825. æD pascal void EndUpdate(WindowPtr theWindow)
  88826.     = 0xA923; 
  88827. æDT EndUpdate((WindowPtr) theWindow);
  88828. æMM
  88829. æRI I-293, P-97, 170
  88830. æC  
  88831. Call EndUpdate to restore the normal visRgn of theWindow’s grafPort, which was changed
  88832. by BeginUpdate as described above.
  88833.  
  88834. æKY SetWRefCon
  88835. æFc Windows.h
  88836. æT Function
  88837. æTN A918
  88838. æD pascal void SetWRefCon(WindowPtr theWindow,long data)
  88839.     = 0xA918; 
  88840. æDT SetWRefCon((WindowPtr) theWindow,(long) data);
  88841. æRI I-293
  88842. æC  
  88843. SetWRefCon sets theWindow’s reference value to the given data.
  88844.  
  88845. æKY GetWRefCon
  88846. æFc Windows.h
  88847. æT Function
  88848. æTN A917
  88849. æD pascal long GetWRefCon(WindowPtr theWindow)
  88850.     = 0xA917; 
  88851. æDT long myVariable = GetWRefCon((WindowPtr) theWindow);
  88852. æRI I-293
  88853. æC  
  88854. GetWRefCon returns theWindow’s current reference value.
  88855.  
  88856. æKY SetWindowPic
  88857. æFc Windows.h
  88858. æT Function
  88859. æTN A92E
  88860. æD pascal void SetWindowPic(WindowPtr theWindow,PicHandle pic)
  88861.     = 0xA92E; 
  88862. æDT SetWindowPic((WindowPtr) theWindow,(PicHandle) pic);
  88863. æRI I-293
  88864. æC  
  88865. SetWindowPic stores the given picture handle in the window record for theWindow, so
  88866. that when theWindow’s contents are to be drawn, the Window Manager will draw this
  88867. picture rather than generate an update event.
  88868.  
  88869. æKY GetWindowPic
  88870. æFc Windows.h
  88871. æT Function
  88872. æTN A92F
  88873. æD pascal PicHandle GetWindowPic(WindowPtr theWindow)
  88874.     = 0xA92F; 
  88875. æDT PicHandle myVariable = GetWindowPic((WindowPtr) theWindow);
  88876. æRI I-293
  88877. æC  
  88878. GetWindowPic returns the handle to the picture that draws theWindow’s contents,
  88879. previously stored with SetWindowPic.
  88880.  
  88881. æKY CheckUpdate
  88882. æFc Windows.h
  88883. æT Function
  88884. æTN A911
  88885. æD pascal Boolean CheckUpdate(EventRecord *theEvent)
  88886.     = 0xA911; 
  88887. æDT Boolean myVariable = CheckUpdate((EventRecord *) theEvent);
  88888. æMM
  88889. æRI I-296
  88890. æC  
  88891. CheckUpdate is called by the Toolbox Event Manager. From the front to the back in the
  88892. window list, it looks for a visible window that needs updating (that is, whose update
  88893. region is not empty). If it finds one whose window record contains a picture handle,
  88894. it draws the picture (doing all the necessary region manipulation) and looks for the
  88895. next visible window that needs updating. If it ever finds one whose window record
  88896. doesn’t contain a picture handle, it stores an update event for that window in theEvent
  88897. and returns TRUE. If it never finds such a window, it returns FALSE.
  88898.  
  88899. æKY ClipAbove
  88900. æFc Windows.h
  88901. æT Function
  88902. æTN A90B
  88903. æD pascal void ClipAbove(WindowPeek window)
  88904.     = 0xA90B; 
  88905. æDT ClipAbove((WindowPeek) window);
  88906. æMM
  88907. æRI I-296
  88908. æC  
  88909. ClipAbove sets the clipRgn of the Window Manager port to be the desktop intersected
  88910. with the current clipRgn, minus the structure regions of all the windows in front of
  88911. the given window.
  88912.  
  88913. Assembly-language note:  ClipAbove gets the desktop region from the global
  88914.                          variable GrayRgn.
  88915.  
  88916. æKY SaveOld
  88917. æFc Windows.h
  88918. æT Function
  88919. æTN A90E
  88920. æD pascal void SaveOld(WindowPeek window)
  88921.     = 0xA90E; 
  88922. æDT SaveOld((WindowPeek) window);
  88923. æMM
  88924. æRI I-296
  88925. æC  
  88926. SaveOld saves the given window’s current structure region and content region for the
  88927. DrawNew operation (see below). It must be balanced by a subsequent call to DrawNew.
  88928.  
  88929. æKY DrawNew
  88930. æFc Windows.h
  88931. æT Function
  88932. æTN A90F
  88933. æD pascal void DrawNew(WindowPeek window,Boolean update)
  88934.     = 0xA90F; 
  88935. æDT DrawNew((WindowPeek) window,(Boolean) update);
  88936. æMM
  88937. æRI I-296
  88938. æC  
  88939. If the update parameter is TRUE, DrawNew updates the area
  88940.  
  88941.   (OldStructure XOR NewStructure) UNION (OldContent XOR NewContent)
  88942.  
  88943. where OldStructure and OldContent are the structure and content regions saved by the
  88944. SaveOld procedure, and NewStructure and NewContent are the current structure and
  88945. content regions. It erases the area and adds it to the window’s update region. If
  88946. update is FALSE, it only erases the area.
  88947.  
  88948. Warning:  In Pascal, SaveOld and DrawNew are not nestable.
  88949.  
  88950. Assembly-language note:  In assembly language, you can nest SaveOld and
  88951.                          DrawNew if you save and restore the values of the
  88952.                          global variables OldStructure and OldContent.
  88953.  
  88954. æKY PaintOne
  88955. æFc Windows.h
  88956. æT Function
  88957. æTN A90C
  88958. æD pascal void PaintOne(WindowPeek window,RgnHandle clobberedRgn)
  88959.     = 0xA90C; 
  88960. æDT PaintOne((WindowPeek) window,(RgnHandle) clobberedRgn);
  88961. æMM
  88962. æRI I-296, V-208
  88963. æC 
  88964. [Macintosh II]
  88965.  
  88966. PaintOne “paints” the given window, clipped to clobberedRgn and all windows above
  88967. it:  It draws the window frame and, if some content is exposed, erases the exposed
  88968. area (paints it with the background pattern) and adds it to the window’s update
  88969. region. If the window parameter is NIL, the window is the desktop and so is painted
  88970. with the desktop pattern.
  88971.  
  88972. The PaintOne routine is modified to improve the performance of updates when differently
  88973. colored windows are in use. Formerly, the Window Manager collected the update region
  88974. of multiple windows into a single region, then erased this single region to white. In
  88975. a color environment, different windows may need to be erased to different colors, so
  88976. the previously used monochrome optimization is disabled. Each uncovered window is now
  88977. erased separately, as if the PaintWhite global variable was always set to TRUE.
  88978. Software that uses the PaintWhite and SaveUpdate flags may appear slightly different
  88979. when update events are being processed.
  88980.  
  88981. PaintOne tests to see if a window has an old or new grafPort, and sets either the
  88982. wMgrPort or wMgrCPort as appropriate. This allows color windows the full RGB range
  88983. when being erased to their content color.
  88984.  
  88985. Assembly-language note:  The global variables SaveUpdate and PaintWhite
  88986.                          are flags used by PaintOne. Normally both flags are
  88987.                          set. Clearing SaveUpdate prevents clobberedRgn from
  88988.                          being added to the window’s update region. Clearing
  88989.                          PaintWhite prevents clobberedRgn from being erased
  88990.                          before being added to the update region (this is
  88991.                          useful, for example, if the background of the window
  88992.                          isn’t the background pattern). The Window Manager
  88993.                          sets both flags periodically, so you should clear
  88994.                          the appropriate flag just before each situation you
  88995.                          wish it to apply to.
  88996.  
  88997. æKY PaintBehind
  88998. æFc Windows.h
  88999. æT Function
  89000. æTN A90D
  89001. æD pascal void PaintBehind(WindowPeek startWindow,RgnHandle clobberedRgn)
  89002.     = 0xA90D; 
  89003. æDT PaintBehind((WindowPeek) startWindow,(RgnHandle) clobberedRgn);
  89004. æMM
  89005. æRI I-297
  89006. æC  
  89007. PaintBehind calls PaintOne for startWindow and all the windows behind startWindow,
  89008. clipped to clobberedRgn.
  89009.  
  89010. Assembly-language note:  PaintBehind clears the global variable PaintWhite
  89011.                          before calling PaintOne, so clobberedRgn isn’t
  89012.                          erased. (PaintWhite is reset after the call to
  89013.                          PaintOne.)
  89014.  
  89015. æKY CalcVis
  89016. æFc Windows.h
  89017. æT Function
  89018. æTN A909
  89019. æD pascal void CalcVis(WindowPeek window)
  89020.     = 0xA909; 
  89021. æDT CalcVis((WindowPeek) window);
  89022. æMM
  89023. æRI I-297
  89024. æC  
  89025. CalcVis calculates the visRgn of the given window by starting with its content region
  89026. and subtracting the structure region of each window in front of it.
  89027.  
  89028. æKY CalcVisBehind
  89029. æFc Windows.h
  89030. æT Function
  89031. æTN A90A
  89032. æD pascal void CalcVisBehind(WindowPeek startWindow,RgnHandle clobberedRgn)
  89033.     = 0xA90A; 
  89034. æDT CalcVisBehind((WindowPeek) startWindow,(RgnHandle) clobberedRgn);
  89035. æMM
  89036. æRI I-297
  89037. æC 
  89038. Assembly-language note:  The macro you invoke to call CalcVisBehind from
  89039.                          assembly language is named _CalcVBehind.
  89040.  
  89041. CalcVisBehind calculates the visRgns of startWindow and all windows behind startWindow
  89042. that intersect clobberedRgn. It should be called after PaintBehind.
  89043.  
  89044. æKY GrowWindow
  89045. æFc Windows.h
  89046. æT Function
  89047. æTN A92B
  89048. æD pascal long GrowWindow(WindowPtr theWindow,Point startPt,const Rect *bBox)
  89049.     = 0xA92B; 
  89050. æDT long myVariable = GrowWindow((WindowPtr) theWindow,(Point) startPt,(const Rect *) bBox);
  89051. æMM
  89052. æRI I-289, V-209, P-98, 174
  89053. æC  
  89054. [Macintosh II]
  89055.  
  89056. When there’s a mouse-down event in the grow region of theWindow, the application
  89057. should call GrowWindow with startPt equal to the point where the mouse button was
  89058. pressed (in global coordinates, as stored in the where field of the event record).
  89059. GrowWindow pulls a grow image of the window around, following the movements of the
  89060. mouse until the button is released. The grow image for a document window is a dotted
  89061. outline of the entire window and also the lines delimiting the title bar, size box,
  89062. and scroll bar areas; Figure 10 illustrates this for a document window containing
  89063. both scroll bars, but the grow image would be the same even if the window contained
  89064. one or no scroll bars. In general, the grow image is defined in the window definition
  89065. function and is whatever is appropriate to show that the window’s size will change.
  89066.  
  89067. On multiple-screen systems, the GrowWindow routine is modified so that windows can be
  89068. stretched only a small amount onto other screens. This restriction can be removed by
  89069. holding down the command key while growing the window, allowing windows to cover the
  89070. full extent of the multiscreen desktop.
  89071.  
  89072. •••Refer to Figure 10.•••
  89073.  
  89074. Figure 10–GrowWindow Operation on a Document Window
  89075.  
  89076. The application should subsequently call SizeWindow to change the portRect of the
  89077. window’s grafPort to the new one outlined by the grow image. The sizeRect parameter
  89078. specifies limits, in pixels, on the vertical and horizontal measurements of what will
  89079. be the new portRect. SizeRect.top is the minimum vertical measurement, sizeRect.left
  89080. is the minimum horizontal measurement, sizeRect.bottom is the maximum vertical measurement,
  89081. and sizeRect.right is the maximum horizontal measurement.
  89082.  
  89083. GrowWindow returns the actual size for the new portRect as outlined by the grow image
  89084. when the mouse button is released. The high-order word of the long integer is the
  89085. vertical measurement in pixels and the low-order word is the horizontal measurement.
  89086. A return value of 0 indicates that the size is the same as that of the current portRect.
  89087.  
  89088. Note:  The Toolbox Utility function HiWord takes a long integer as a
  89089.        parameter and returns an integer equal to its high-order word; the
  89090.        function LoWord returns the low-order word.
  89091.  
  89092. Assembly-language note:  Like TrackGoAway, GrowWindow repeatedly calls the
  89093.                          procedure pointed to by the global variable DragHook
  89094.                          (if any) as long as the mouse button is held down.
  89095.  
  89096. æKY trackgoaway
  89097. æFc Windows.h
  89098. æT Function
  89099. æD Boolean trackgoaway(WindowPtr theWindow,Point *thePt); 
  89100. æDT Boolean myVariable = trackgoaway((WindowPtr) theWindow,(Point *) thePt);
  89101. æMM
  89102. æRI I-288, P-98, 184
  89103. æC  
  89104. When there’s a mouse-down event in the go-away region of theWindow, the application
  89105. should call TrackGoAway with thePt equal to the point where the mouse button was
  89106. pressed (in global coordinates, as stored in the where field of the event record).
  89107. TrackGoAway keeps control until the mouse button is released, highlighting the go-away
  89108. region as long as the mouse location remains inside it, and unhighlighting it when
  89109. the mouse moves outside it. The exact way a window’s go-away region is highlighted
  89110. depends on its window definition function; the highlighting of a document window’s
  89111. close box is illustrated in Figure 9. When the mouse button is released, TrackGoAway
  89112. unhighlights the go-away region and returns TRUE if the mouse is inside the go-away
  89113. region or FALSE if it’s outside the region (in which case the application should do
  89114. nothing).
  89115.  
  89116. •••Refer to Figure 9.•••
  89117.  
  89118. Figure 9–A Document Window’s Close Box
  89119.  
  89120. Assembly-language note:  If you store a pointer to a procedure in the
  89121.                          global variable DragHook, TrackGoAway will call
  89122.                          that procedure repeatedly (with no parameters) for
  89123.                          as long as the user holds down the mouse button.
  89124.  
  89125. æKY FindWindow
  89126. æFc Windows.h
  89127. æT Function
  89128. æTN A92C
  89129. æD pascal short FindWindow(Point thePoint,WindowPtr *theWindow)
  89130.     = 0xA92C; 
  89131. æDT short myVariable = FindWindow((Point) thePoint,(WindowPtr *) theWindow);
  89132. æRI I-287, P-35, 114, 170 FindWindow procedure  V-208
  89133. æC  [Macintosh Plus, Macintosh SE, Macintosh II]
  89134.  
  89135. When a mouse-down event occurs, the application should call FindWindow with thePt
  89136. equal to the point where the mouse button was pressed (in global coordinates, as
  89137. stored in the where field of the event record). FindWindow tells which part of which
  89138. window, if any, the mouse button was pressed in. If it was pressed in a window, the
  89139. whichWindow parameter is set to the window pointer; otherwise, it’s set to NIL. The
  89140. integer returned by FindWindow is one of the following predefined constants:
  89141.  
  89142. CONST  inDesk      = 0;    {none of the following}
  89143.        inMenuBar   = 1;    {in menu bar}
  89144.        inSysWindow = 2;    {in system window}
  89145.        inContent   = 3;    {in content region (except grow, if active)}
  89146.        inDrag      = 4;    {in drag region}
  89147.        inGrow      = 5;    {in grow region (active window only)}
  89148.        inGoAway    = 6;    {in go-away region (active window only)}
  89149.  
  89150. InDesk usually means that the mouse button was pressed on the desktop, outside the
  89151. menu bar or any windows; however, it may also mean that the mouse button was pressed
  89152. inside a window frame but not in the drag region or go-away region of the window.
  89153. Usually one of the last four values is returned for windows created by the application.
  89154.  
  89155. The FindWindow procedure now calls the new menu bar definition procedure to determine
  89156. whether the point where the mouse button was pressed lies in the menu bar.
  89157.  
  89158. Assembly-language note:  If you store a pointer to a procedure in the
  89159.                          global variable DeskHook, it will be called when
  89160.                          the mouse button is pressed on the desktop. The
  89161.                          DeskHook procedure will be called with –1 in
  89162.                          register D0 to distinguish this use of it from its
  89163.                          use in drawing the desktop (discussed in the
  89164.                          description of InitWindows). Register A0 will
  89165.                          contain a pointer to the event record for the
  89166.                          mouse-down event. When you use DeskHook in this
  89167.                          way FindWindow does not return inDesk when the
  89168.                          mouse button is pressed on the desktop; it
  89169.                          returns inSysWindow, and the Desk Manager procedure
  89170.                          SystemClick calls the DeskHook procedure.
  89171.  
  89172. If the window is a documentProc type of window that doesn’t contain a size box, the
  89173. application should treat inGrow the same as inContent; if it’s a noGrowDocProc type
  89174. of window, FindWindow will never return inGrow for that window. If the window is a
  89175. documentProc, noGrowDocProc, or rDocProc type of window with no close box, FindWindow
  89176. will never return inGoAway for that window.
  89177.  
  89178. æKY findwindow
  89179. æFc Windows.h
  89180. æT Function
  89181. æD short findwindow(Point *thePoint,WindowPtr *theWindow); 
  89182. æDT short myVariable = findwindow((Point *) thePoint,(WindowPtr *) theWindow);
  89183. æRI I-287, P-35, 114, 170 FindWindow procedure  V-208
  89184. æC  [Macintosh Plus, Macintosh SE, Macintosh II]
  89185.  
  89186. When a mouse-down event occurs, the application should call FindWindow with thePt
  89187. equal to the point where the mouse button was pressed (in global coordinates, as
  89188. stored in the where field of the event record). FindWindow tells which part of which
  89189. window, if any, the mouse button was pressed in. If it was pressed in a window, the
  89190. whichWindow parameter is set to the window pointer; otherwise, it’s set to NIL. The
  89191. integer returned by FindWindow is one of the following predefined constants:
  89192.  
  89193. CONST  inDesk      = 0;    {none of the following}
  89194.        inMenuBar   = 1;    {in menu bar}
  89195.        inSysWindow = 2;    {in system window}
  89196.        inContent   = 3;    {in content region (except grow, if active)}
  89197.        inDrag      = 4;    {in drag region}
  89198.        inGrow      = 5;    {in grow region (active window only)}
  89199.        inGoAway    = 6;    {in go-away region (active window only)}
  89200.  
  89201. InDesk usually means that the mouse button was pressed on the desktop, outside the
  89202. menu bar or any windows; however, it may also mean that the mouse button was pressed
  89203. inside a window frame but not in the drag region or go-away region of the window.
  89204. Usually one of the last four values is returned for windows created by the application.
  89205.  
  89206. The FindWindow procedure now calls the new menu bar definition procedure to determine
  89207. whether the point where the mouse button was pressed lies in the menu bar.
  89208.  
  89209. Assembly-language note:  If you store a pointer to a procedure in the
  89210.                          global variable DeskHook, it will be called when
  89211.                          the mouse button is pressed on the desktop. The
  89212.                          DeskHook procedure will be called with –1 in
  89213.                          register D0 to distinguish this use of it from its
  89214.                          use in drawing the desktop (discussed in the
  89215.                          description of InitWindows). Register A0 will
  89216.                          contain a pointer to the event record for the
  89217.                          mouse-down event. When you use DeskHook in this
  89218.                          way FindWindow does not return inDesk when the
  89219.                          mouse button is pressed on the desktop; it
  89220.                          returns inSysWindow, and the Desk Manager procedure
  89221.                          SystemClick calls the DeskHook procedure.
  89222.  
  89223. If the window is a documentProc type of window that doesn’t contain a size box, the
  89224. application should treat inGrow the same as inContent; if it’s a noGrowDocProc type
  89225. of window, FindWindow will never return inGrow for that window. If the window is a
  89226. documentProc, noGrowDocProc, or rDocProc type of window with no close box, FindWindow
  89227. will never return inGoAway for that window.
  89228.  
  89229. æKY PinRect
  89230. æFc Windows.h
  89231. æT Function
  89232. æTN A94E
  89233. æD pascal long PinRect(const Rect *theRect,Point thePt)
  89234.     = 0xA94E; 
  89235. æDT long myVariable = PinRect((const Rect *) theRect,(Point) thePt);
  89236. æRI I-293
  89237. æC  
  89238. PinRect “pins” thePt inside theRect:  If thePt is inside theRect, thePt is returned;
  89239. otherwise, the point associated with the nearest pixel within theRect is returned.
  89240. (The high-order word of the long integer returned is the vertical coordinate; the
  89241. low-order word is the horizontal coordinate.) More precisely, for theRect (left,top)
  89242. (right,bottom) and thePt (h,v), PinRect does the following:
  89243.  
  89244.   •  If h < left, it returns left.
  89245.   •  If v < top, it returns top.
  89246.   •  If h > right, it returns right–1.
  89247.   •  If v > bottom, it returns bottom–1.
  89248.  
  89249. Note:  The 1 is subtracted when thePt is below or to the right of theRect
  89250.        so that a pixel drawn at that point will lie within theRect. However,
  89251.        if thePt is exactly on the bottom or right edge of theRect, 1 should
  89252.        be subtracted but isn’t.
  89253.  
  89254. æKY DragGrayRgn
  89255. æFc Windows.h
  89256. æT Function
  89257. æTN A905
  89258. æD pascal long DragGrayRgn(RgnHandle theRgn,Point startPt,const Rect *boundsRect,
  89259.     const Rect *slopRect,short axis,DragGrayRgnProcPtr actionProc)
  89260.     = 0xA905; 
  89261. æDT long myVariable = DragGrayRgn((RgnHandle) theRgn,(Point) startPt,(const Rect *) boundsRect,(
  89262.     const Rect) * slopRect,(short) axis,(DragGrayRgnProcPtr) actionProc);
  89263. æMM
  89264. æRT 193
  89265. æRI I-294, V-209
  89266. æC  
  89267. [Macintosh II]
  89268.  
  89269. Called when the mouse button is down inside theRgn, DragGrayRgn pulls a dotted
  89270. (gray) outline of the region around, following the movements of the mouse until the
  89271. button is released. DragWindow calls this function before actually moving the window.
  89272. You can call it yourself to pull around the outline of any region, and then use the
  89273. information it returns to determine where to move the region.
  89274.  
  89275. On multiple-screen systems, the Window Manager now checks the screen rectangle
  89276. (screenBits.bounds) when the DragGrayRgn routine is called. This allows the object
  89277. being dragged to be positioned anywhere on the multiscreen desktop. If the dragging
  89278. bounds are based on screenBits.bound, the dragging boundsRect will be changed to the
  89279. bounding box of the grayRgn. The Window Manager’s criteria for modifying the bounds
  89280. are (1) the left, bottom, and right are within six pixels of screenBits.bound, and
  89281. (2) the top is within 36 pixels of screenBits.bounds.top. If the dragging bounds are
  89282. modified, the lmitRect parameter is also similarly modified.
  89283.  
  89284. Note:  DragGrayRgn alters the region; if you don’t want the original region
  89285.        changed, pass DragGrayRgn a handle to a copy.
  89286.  
  89287. The startPt parameter is assumed to be the point where the mouse button was originally
  89288. pressed, in the local coordinates of the current grafPort.
  89289.  
  89290. LmitRect and slopRect are also in the local coordinates of the current grafPort. To
  89291. explain these parameters, the concept of “offset point” must be introduced:  This is
  89292. initially the point whose vertical and horizontal offsets from the top left corner of
  89293. the region’s enclosing rectangle are the same as those of startPt. The offset point
  89294. follows the mouse location, except that DragGrayRgn will never move the offset point
  89295. outside limitRect; this limits the travel of the region’s outline (but not the movements
  89296. of the mouse). SlopRect, which should completely enclose limitRect, allows the user
  89297. some “slop” in moving the mouse. DragGrayRgn’s behavior while tracking the mouse
  89298. depends on the location of the mouse with respect to these two rectangles:
  89299.  
  89300.   •  When the mouse is inside lmitRect, the region’s outline follows it
  89301.      normally. If the mouse button is released there, the region should be
  89302.      moved to the mouse location.
  89303.   •  When the mouse is outside lmitRect but inside slopRect, DragGrayRgn
  89304.      “pins” the offset point to the edge of lmitRect. If the mouse button
  89305.      is released there, the region should be moved to this pinned location.
  89306.   •  When the mouse is outside slopRect, the outline disappears from the
  89307.      screen, but DragGrayRgn continues to follow the mouse; if it moves back
  89308.      into slopRect, the outline reappears. If the mouse button is released
  89309.      outside slopRect, the region should not be moved from its original
  89310.      position.
  89311.  
  89312. Figure 13 illustrates what happens when the mouse is moved outside lmitRect but
  89313. inside slopRect, for a rectangular region. The offset point is pinned as the mouse
  89314. location moves on.
  89315.  
  89316. If the mouse button is released within slopRect, the high-order word of the value
  89317. returned by DragGrayRgn contains the vertical coordinate of the ending mouse location
  89318. minus that of startPt and the low-order word contains the difference between the
  89319. horizontal coordinates. If the mouse button is released outside slopRect, both words
  89320. contain –32768 ($8000).
  89321.  
  89322. •••Refer to Figure 13.•••
  89323.  
  89324. Figure 13–DragGrayRgn Operation on a Rectangular Region
  89325.  
  89326. The axis parameter allows you to constrain the region’s motion to only one axis. It
  89327. has one of the following values:
  89328.  
  89329. CONST  noConstraint = 0;    {no constraint}
  89330.        hAxisOnly    = 1;    {horizontal axis only}
  89331.        vAxisOnly    = 2;    {vertical axis only}
  89332.  
  89333. If an axis constraint is in effect, the outline will follow the mouse’s movements
  89334. along the specified axis only, ignoring motion along the other axis. With or without
  89335. an axis constraint, the mouse must still be inside the slop rectangle for the outline
  89336. to appear at all.
  89337.  
  89338. The actionProc parameter is a pointer to a procedure that defines some action to be
  89339. performed repeatedly for as long as the user holds down the mouse button; the procedure
  89340. should have no parameters. If actionProc is NIL, DragGrayRgn simply retains control
  89341. until the mouse button is released.
  89342.  
  89343. Assembly-language note:  DragGrayRgn calls the procedure pointed to by the
  89344.                          global variable DragHook, if any, as long as the
  89345.                          mouse button is held down. (If there’s an actionProc
  89346.                          procedure, the actionProc procedure is called first.)
  89347.  
  89348.                          If you want the region’s outline to be drawn in a
  89349.                          pattern other than gray, you can store the pattern in
  89350.                          the global variable DragPattern and then invoke the
  89351.                          macro _DragTheRgn.
  89352.  
  89353. æKY TrackBox
  89354. æFc Windows.h
  89355. æT Function
  89356. æTN A83B
  89357. æD pascal Boolean TrackBox(WindowPtr theWindow,Point thePt,short partCode)
  89358.     = 0xA83B; 
  89359. æDT Boolean myVariable = TrackBox((WindowPtr) theWindow,(Point) thePt,(short) partCode);
  89360. æMM
  89361. æRT 79
  89362. æRI IV-50, N79-1
  89363. æC  
  89364. When there’s a mouse-down event in the zoom-window box of theWindow, the application
  89365. should call TrackBox with thePt equal to the point where the mouse button was pressed
  89366. (in global coordinates, as stored in the where field of the event record). The partCode
  89367. parameter contains the constant (either inZoomIn or inZoomOut) returned by FindWindow.
  89368. TrackBox keeps control until the mouse button is released; it highlights the zoom-window
  89369. box in the same way as a window’s close box is highlighted. When the mouse button is
  89370. released, TrackBox unhighlights the zoom-window box and returns TRUE if the mouse is
  89371. inside the zoom-window box or FALSE if it’s outside the box (in which case the application
  89372. should do nothing).
  89373.  
  89374. æKY GetCWMgrPort
  89375. æFc Windows.h
  89376. æT Function
  89377. æTN AA48
  89378. æD pascal void GetCWMgrPort(CGrafPtr *wMgrCPort)
  89379.     = 0xAA48; 
  89380. æDT GetCWMgrPort((CGrafPtr *) wMgrCPort);
  89381. æRI V-210
  89382. æC 
  89383. The WMgrCPort is a parallel structure to the WMgrPort. The GetCWMgrPort returns the
  89384. address of the WMgrCPort. In Apple-provided 'WDEF' resources, all drawing is done in
  89385. the WMgrCPort to allow full color drawing, rather than just the eight QuickDraw
  89386. colors.
  89387.  
  89388. æKY getwtitle
  89389. æFc Windows.h
  89390. æT Function
  89391. æD void getwtitle(WindowPtr theWindow,char *title); 
  89392. æDT getwtitle((WindowPtr) theWindow,(char *) title);
  89393. æRI I-284
  89394. æC  
  89395. GetWTitle returns theWindow's title as the value of the title parameter.
  89396.  
  89397. æKY SetWinColor
  89398. æFc Windows.h
  89399. æT Function
  89400. æTN AA41
  89401. æD pascal void SetWinColor(WindowPtr theWindow,WCTabHandle newColorTable)
  89402.     = 0xAA41; 
  89403. æDT SetWinColor((WindowPtr) theWindow,(WCTabHandle) newColorTable);
  89404. æMM
  89405. æRI V-207
  89406. æC 
  89407. [Macintosh II]
  89408.  
  89409. The SetWinColor routine sets a window’s color table.  If the window currently has no
  89410. auxiliary window record, a new one is created with the given color table and added to
  89411. the head of the auxiliary window list.  If there is already an auxiliary record for
  89412. the window, its color table is replaced by the contents of newColorTable. The window
  89413. is then automatically redrawn in the new colors. If SetWinColor is performed on a
  89414. cWindow, it sets the backColor of the window to the new content color. This allows an
  89415. application to begin its update without changing the background color.
  89416.  
  89417. If newColorTable has the same contents as the default color table, the window’s
  89418. existing auxiliary record and color table are removed from the auxiliary window list
  89419. and deallocated.  If theWindow = NIL, the operation modifies the default color table
  89420. in memory. The system never disposes of color tables that are resources when the
  89421. resource bit is set; 'wctb' resources can’t be purgeable.
  89422.  
  89423. æKY GetAuxWin
  89424. æFc Windows.h
  89425. æT Function
  89426. æTN AA42
  89427. æD pascal Boolean GetAuxWin(WindowPtr theWindow,AuxWinHandle *awHndl)
  89428.     = 0xAA42; 
  89429. æDT Boolean myVariable = GetAuxWin((WindowPtr) theWindow,(AuxWinHandle *) awHndl);
  89430. æRI V-207
  89431. æC 
  89432. The GetAuxWin routine returns a handle to a window’s auxiliary window record:
  89433.  
  89434.   •  If the given window has an auxiliary record, its handle is returned in
  89435.      awHndl and the function returns TRUE.
  89436.   •  If the window has no auxiliary record, a handle to the default record
  89437.      is returned in awHndl and the function returns FALSE.
  89438.   •  If theWindow = NIL, a handle to the default record is returned in awHndl
  89439.      and the function returns TRUE.
  89440.  
  89441. æKY growwindow
  89442. æFc Windows.h
  89443. æT Function
  89444. æD long growwindow(WindowPtr theWindow,Point *startPt,const Rect *bBox); 
  89445. æDT long myVariable = growwindow((WindowPtr) theWindow,(Point *) startPt,(const Rect *) bBox);
  89446. æRI I-289, V-209, P-98, 174
  89447. æC  
  89448. [Macintosh II]
  89449.  
  89450. When there’s a mouse-down event in the grow region of theWindow, the application
  89451. should call GrowWindow with startPt equal to the point where the mouse button was
  89452. pressed (in global coordinates, as stored in the where field of the event record).
  89453. GrowWindow pulls a grow image of the window around, following the movements of the
  89454. mouse until the button is released. The grow image for a document window is a dotted
  89455. outline of the entire window and also the lines delimiting the title bar, size box,
  89456. and scroll bar areas; Figure 10 illustrates this for a document window containing
  89457. both scroll bars, but the grow image would be the same even if the window contained
  89458. one or no scroll bars. In general, the grow image is defined in the window definition
  89459. function and is whatever is appropriate to show that the window’s size will change.
  89460.  
  89461. On multiple-screen systems, the GrowWindow routine is modified so that windows can be
  89462. stretched only a small amount onto other screens. This restriction can be removed by
  89463. holding down the command key while growing the window, allowing windows to cover the
  89464. full extent of the multiscreen desktop.
  89465.  
  89466. •••Refer to Figure 10.•••
  89467.  
  89468. Figure 10–GrowWindow Operation on a Document Window
  89469.  
  89470. The application should subsequently call SizeWindow to change the portRect of the
  89471. window’s grafPort to the new one outlined by the grow image. The sizeRect parameter
  89472. specifies limits, in pixels, on the vertical and horizontal measurements of what will
  89473. be the new portRect. SizeRect.top is the minimum vertical measurement, sizeRect.left
  89474. is the minimum horizontal measurement, sizeRect.bottom is the maximum vertical measurement,
  89475. and sizeRect.right is the maximum horizontal measurement.
  89476.  
  89477. GrowWindow returns the actual size for the new portRect as outlined by the grow image
  89478. when the mouse button is released. The high-order word of the long integer is the
  89479. vertical measurement in pixels and the low-order word is the horizontal measurement.
  89480. A return value of 0 indicates that the size is the same as that of the current portRect.
  89481.  
  89482. Note:  The Toolbox Utility function HiWord takes a long integer as a
  89483.        parameter and returns an integer equal to its high-order word; the
  89484.        function LoWord returns the low-order word.
  89485.  
  89486. Assembly-language note:  Like TrackGoAway, GrowWindow repeatedly calls the
  89487.                          procedure pointed to by the global variable DragHook
  89488.                          (if any) as long as the mouse button is held down.
  89489.  
  89490. æKY SetDeskCPat
  89491. æFc Windows.h
  89492. æT Function
  89493. æTN AA47
  89494. æD pascal void SetDeskCPat(PixPatHandle deskPixPat)
  89495.     = 0xAA47; 
  89496. æDT SetDeskCPat((PixPatHandle) deskPixPat);
  89497. æMM
  89498. æRI V-210
  89499. æC 
  89500. Note:  This routine is not for use by applications, and its description is
  89501.        only included for informational purposes.
  89502.  
  89503. The SetDeskCPat procedure sets the desktop pattern to a given pixel pattern, allowing
  89504. it to be drawn in more than two colors if desired.  The desktop is automatically
  89505. redrawn in the new pattern.  If deskPixPat is an old-style binary pattern (patType =
  89506. 0), it will be drawn in the current foreground and background colors. If the pixPatHandle
  89507. is NIL, the standard binary deskPat
  89508. ('ppat' resource = 16) will be used.
  89509.  
  89510. The standard desktop painting routines can paint either in the existing binary pattern
  89511. (kept in global variable DeskPat) or in a new pixel pattern. The desk pattern used at
  89512. startup is determined by the value of another bit flag called pCDeskPat. If this is
  89513. pCDeskPat = 0, the new pixel pattern is used; for all other values, the binary pattern
  89514. is used by default. The color pattern can be changed through use of the Control Panel
  89515. or through the use of SetDeskCPat, but only the Control Panel changes the value of
  89516. pCDeskPat in parameter RAM.
  89517.  
  89518. æKY newwindow
  89519. æFc Windows.h
  89520. æT Function
  89521. æD WindowPtr newwindow(Ptr wStorage,const Rect *boundsRect,char *title,Boolean visible,
  89522.     short theProc,WindowPtr behind,Boolean goAwayFlag,long refCon); 
  89523. æDT WindowPtr myVariable = newwindow((Ptr) wStorage,(const Rect *) boundsRect,(char *) title,(Boolean) visible,()
  89524.     short theProc,(WindowPtr) behind,(Boolean) goAwayFlag,(long) refCon);
  89525. æMM
  89526. æRI I-282, P-95, 178
  89527. æC  
  89528. NewWindow creates a window as specified by its parameters, adds it to the window
  89529. list, and returns a windowPtr to the new window. It allocates space for the structure
  89530. and content regions of the window and asks the window definition function to calculate
  89531. those regions.
  89532.  
  89533. WStorage is a pointer to where to store the window record. For example, if
  89534. you’ve declared the variable wRecord of type WindowRecord, you can pass @wRecord as
  89535. the first parameter to NewWindow. If you pass NIL for wStorage, the window record
  89536. will be allocated as a nonrelocatable object in the heap; in that case, though, you
  89537. risk ending up with a fragmented heap.
  89538.  
  89539. BoundsRect, a rectangle given in global coordinates, determines the window’s size and
  89540. location, and becomes the portRect of the window’s grafPort; note, however, that the
  89541. portRect is in local coordinates. NewWindow sets the top left corner of the portRect
  89542. to (0,0). For the standard types of windows, the boundsRect defines the content
  89543. region of the window.
  89544.  
  89545. Note:  The bit map, pen pattern, and other characteristics of the window’s
  89546.        grafPort are the same as the default values set by the OpenPort
  89547.        procedure in QuickDraw, except for the character font, which is set
  89548.        to the application font rather than the system font. (NewWindow
  89549.        actually calls OpenPort to initialize the window’s grafPort.) Note,
  89550.        however, that the coordinates of the grafPort’s portBits.bounds and
  89551.        visRgn are changed along with its portRect.
  89552.  
  89553. The title parameter is the window’s title. If the title of a document window is
  89554. longer than will fit in the title bar, it’s truncated in one of two ways:  If the
  89555. window has a close box, the characters that don’t fit are truncated from the end of
  89556. the title; if there’s no close box, the title is centered and truncated at both
  89557. ends.
  89558.  
  89559. If the visible parameter is TRUE, NewWindow draws the window. First it calls the
  89560. window definition function to draw the window frame; if goAwayFlag is also TRUE and
  89561. the window is frontmost (as specified by the behind parameter, below), it draws a
  89562. go-away region in the frame. Then it generates an update event for the entire window
  89563. contents.
  89564.  
  89565. ProcID is the window definition ID, which leads to the window definition function for
  89566. this type of window. The function is read into memory if it’s not already in memory.
  89567. If it can’t be read, NewWindow returns NIL. The window definition IDs for the standard
  89568. types of windows are listed above under
  89569. “Windows and Resources”. Window definition IDs for windows of your own design are
  89570. discussed later under “Defining Your Own Windows”.
  89571.  
  89572. The behind parameter determines the window’s plane. The new window is inserted in
  89573. back of the window pointed to by this parameter. To put the new window behind all
  89574. other windows, use behind=NIL. To place it in front of all other windows, use behind=POINTER(–1);
  89575. in this case, NewWindow will unhighlight the previously active window, highlight the
  89576. window being created, and generate appropriate activate events.
  89577.  
  89578. RefCon is the window’s reference value, set and used only by your application.
  89579.  
  89580. NewWindow also sets the window class in the window record to indicate that the window
  89581. was created directly by the application.
  89582.  
  89583. æKY NewCWindow
  89584. æFc Windows.h
  89585. æT Function
  89586. æTN AA45
  89587. æD pascal WindowPtr NewCWindow(Ptr wStorage,const Rect *boundsRect,const Str255 title,
  89588.     Boolean visible,short procID,WindowPtr behind,Boolean goAwayFlag,long refCon)
  89589.     = 0xAA45; 
  89590. æDT WindowPtr myVariable = NewCWindow((Ptr) wStorage,(const Rect *) boundsRect,(const Str255) title,()
  89591.     Boolean visible,(short) procID,(WindowPtr) behind,(Boolean) goAwayFlag,(long) refCon);
  89592. æMM
  89593. æRI V-207
  89594. æC 
  89595. [Macintosh II]
  89596.  
  89597. The NewCWindow routine creates a new color window.  This routine is similar to the
  89598. old routine NewWindow, but creates a window based on a cGrafPort instead of an old-style
  89599. grafPort.
  89600.  
  89601. æKY newcwindow
  89602. æFc Windows.h
  89603. æT Function
  89604. æD WindowPtr newcwindow(Ptr wStorage,const Rect *boundsRect,char *title,Boolean visible,
  89605.     short procID,WindowPtr behind,Boolean goAwayFlag,long refCon); 
  89606. æDT WindowPtr myVariable = newcwindow((Ptr) wStorage,(const Rect *) boundsRect,(char *) title,(Boolean) visible,()
  89607.     short procID,(WindowPtr) behind,(Boolean) goAwayFlag,(long) refCon);
  89608. æRI V-207
  89609. æC 
  89610. [Macintosh II]
  89611.  
  89612. The NewCWindow routine creates a new color window.  This routine is similar to the
  89613. old routine NewWindow, but creates a window based on a cGrafPort instead of an old-style
  89614. grafPort.
  89615.  
  89616. æKY GetNewCWindow
  89617. æFc Windows.h
  89618. æT Function
  89619. æTN AA46
  89620. æD pascal WindowPtr GetNewCWindow(short windowID,Ptr wStorage,WindowPtr behind)
  89621.     = 0xAA46; 
  89622. æDT WindowPtr myVariable = GetNewCWindow((short) windowID,(Ptr) wStorage,(WindowPtr) behind);
  89623. æMM
  89624. æRI V-207
  89625. æC 
  89626.  
  89627. The GetNewCWindow routine creates a new color window from a template in a resource
  89628. file. It’s analogous to the old routine GetNewWindow, but it creates a window based
  89629. on a cGrafPort instead of an old-style grafPort. GetNewCWindow checks the 'wctb'
  89630. resource, and if it contains the same resource ID, it colors the window. The backColor
  89631. of the window is set to the new content color. This allows an application to begin
  89632. its update with an EraseRect without changing the background color.
  89633.  
  89634. æKY GetWVariant
  89635. æFc Windows.h
  89636. æT Function
  89637. æTN A80A
  89638. æD pascal short GetWVariant(WindowPtr theWindow)
  89639.     = 0xA80A; 
  89640. æDT short myVariable = GetWVariant((WindowPtr) theWindow);
  89641. æRI V-208
  89642. æC 
  89643. [Macintosh Plus, Macintosh SE, Macintosh II]
  89644.  
  89645. GetWVariant returns the variant code for the window described by whichWindow. See the
  89646. section “Defining Your Own Windows” for more information about variants.
  89647.  
  89648. æKY pinrect
  89649. æFc Windows.h
  89650. æT Function
  89651. æD long pinrect(const Rect *theRect,Point *thePt); 
  89652. æDT long myVariable = pinrect((const Rect *) theRect,(Point *) thePt);
  89653. æRI I-293
  89654. æC  
  89655. PinRect “pins” thePt inside theRect:  If thePt is inside theRect, thePt is returned;
  89656. otherwise, the point associated with the nearest pixel within theRect is returned.
  89657. (The high-order word of the long integer returned is the vertical coordinate; the
  89658. low-order word is the horizontal coordinate.) More precisely, for theRect (left,top)
  89659. (right,bottom) and thePt (h,v), PinRect does the following:
  89660.  
  89661.   •  If h < left, it returns left.
  89662.   •  If v < top, it returns top.
  89663.   •  If h > right, it returns right–1.
  89664.   •  If v > bottom, it returns bottom–1.
  89665.  
  89666. Note:  The 1 is subtracted when thePt is below or to the right of theRect
  89667.        so that a pixel drawn at that point will lie within theRect. However,
  89668.        if thePt is exactly on the bottom or right edge of theRect, 1 should
  89669.        be subtracted but isn’t.
  89670.  
  89671. æKY GetGrayRgn
  89672. æFc Windows.h
  89673. æT Function
  89674. æD pascal RgnHandle GetGrayRgn(void); 
  89675. æDT RgnHandle myVariable = GetGrayRgn()(void);
  89676. æMM
  89677. æRI V-208
  89678. æC 
  89679. [Macintosh Plus, Macintosh SE, Macintosh II]
  89680.  
  89681. The GetGrayRgn function returns a handle to the current desktop region stored in the
  89682. global variable GrayRgn.
  89683.  
  89684. æKY SetWTitle
  89685. æFc Windows.h
  89686. æT Function
  89687. æTN A91A
  89688. æD pascal void SetWTitle(WindowPtr theWindow,const Str255 title)
  89689.     = 0xA91A; 
  89690. æDT SetWTitle((WindowPtr) theWindow,(const Str255) title);
  89691. æMM
  89692. æRI I-284
  89693. æC  
  89694. SetWTitle sets theWindow’s title to the given string, performing any necessary redrawing
  89695. of the window frame.
  89696.  
  89697. æKY trackbox
  89698. æFc Windows.h
  89699. æT Function
  89700. æD Boolean trackbox(WindowPtr theWindow,Point *thePt,short partCode); 
  89701. æDT Boolean myVariable = trackbox((WindowPtr) theWindow,(Point *) thePt,(short) partCode);
  89702. æMM
  89703. æRT 79
  89704. æRI IV-50
  89705. æC  
  89706. When there’s a mouse-down event in the zoom-window box of theWindow, the application
  89707. should call TrackBox with thePt equal to the point where the mouse button was pressed
  89708. (in global coordinates, as stored in the where field of the event record). The partCode
  89709. parameter contains the constant (either inZoomIn or inZoomOut) returned by FindWindow.
  89710. TrackBox keeps control until the mouse button is released; it highlights the zoom-window
  89711. box in the same way as a window’s close box is highlighted. When the mouse button is
  89712. released, TrackBox unhighlights the zoom-window box and returns TRUE if the mouse is
  89713. inside the zoom-window box or FALSE if it’s outside the box (in which case the application
  89714. should do nothing).
  89715.  
  89716. æKY TrackGoAway
  89717. æFc Windows.h
  89718. æT Function
  89719. æTN A91E
  89720. æD pascal Boolean TrackGoAway(WindowPtr theWindow,Point thePt)
  89721.     = 0xA91E; 
  89722. æDT Boolean myVariable = TrackGoAway((WindowPtr) theWindow,(Point) thePt);
  89723. æMM
  89724. æRI I-288, P-98, 184
  89725. æC  
  89726. When there’s a mouse-down event in the go-away region of theWindow, the application
  89727. should call TrackGoAway with thePt equal to the point where the mouse button was
  89728. pressed (in global coordinates, as stored in the where field of the event record).
  89729. TrackGoAway keeps control until the mouse button is released, highlighting the go-away
  89730. region as long as the mouse location remains inside it, and unhighlighting it when
  89731. the mouse moves outside it. The exact way a window’s go-away region is highlighted
  89732. depends on its window definition function; the highlighting of a document window’s
  89733. close box is illustrated in Figure 9. When the mouse button is released, TrackGoAway
  89734. unhighlights the go-away region and returns TRUE if the mouse is inside the go-away
  89735. region or FALSE if it’s outside the region (in which case the application should do
  89736. nothing).
  89737.  
  89738. •••Refer to Figure 9.•••
  89739.  
  89740. Figure 9–A Document Window’s Close Box
  89741.  
  89742. Assembly-language note:  If you store a pointer to a procedure in the
  89743.                          global variable DragHook, TrackGoAway will call
  89744.                          that procedure repeatedly (with no parameters) for
  89745.                          as long as the user holds down the mouse button.
  89746.  
  89747. æKY DragWindow
  89748. æFc Windows.h
  89749. æT Function
  89750. æTN A925
  89751. æD pascal void DragWindow(WindowPtr theWindow,Point startPt,const Rect *boundsRect)
  89752.     = 0xA925; 
  89753. æDT DragWindow((WindowPtr) theWindow,(Point) startPt,(const Rect *) boundsRect);
  89754. æMM
  89755. æRI I-289, P-98, 169
  89756. æC  
  89757. When there’s a mouse-down event in the drag region of theWindow, the application
  89758. should call DragWindow with startPt equal to the point where the mouse button was
  89759. pressed (in global coordinates, as stored in the where field of the event record).
  89760. DragWindow pulls a dotted outline of theWindow around, following the movements of the
  89761. mouse until the button is released. When the mouse button is released, DragWindow
  89762. calls MoveWindow to move theWindow to the location to which it was dragged. If theWindow
  89763. isn’t the active window (and the Command key wasn’t being held down), DragWindow
  89764. makes it the active window by passing TRUE for the front parameter when calling
  89765. MoveWindow. If the Command key was being held down, the window is moved without being
  89766. made the active window.
  89767.  
  89768. BoundsRect is also given in global coordinates. If the mouse button is released when
  89769. the mouse location is outside the limits of boundsRect, DragWindow returns without
  89770. moving theWindow or making it the active window. For a document window, boundsRect
  89771. typically will be four pixels in from the menu bar and from the other edges of the
  89772. screen, to ensure that there won’t be less than a four-pixel-square area of the title
  89773. bar visible on the screen.
  89774.  
  89775. Assembly-language note:  As for TrackGoAway, if you store a pointer to a
  89776.                          procedure in the global variable DragHook, that
  89777.                          procedure will be called repeatedly while the user
  89778.                          holds down the mouse button. (DragWindow calls
  89779.                          DragGrayRgn, which calls the DragHook procedure).
  89780.  
  89781. æKY draggrayrgn
  89782. æFc Windows.h
  89783. æT Function
  89784. æTN A905
  89785. æD long draggrayrgn(RgnHandle theRgn,Point *startPt,const Rect *boundsRect,
  89786.     const Rect *slopRect,short axis,DragGrayRgnProcPtr actionProc); 
  89787. æDT long myVariable = draggrayrgn((RgnHandle) theRgn,(Point *) startPt,(const Rect *) boundsRect,(
  89788.     const Rect) * slopRect,(short) axis,(DragGrayRgnProcPtr) actionProc);
  89789. æRT 193
  89790. æRI I-294, V-209
  89791. æC  
  89792. [Macintosh II]
  89793.  
  89794. Called when the mouse button is down inside theRgn, DragGrayRgn pulls a dotted
  89795. (gray) outline of the region around, following the movements of the mouse until the
  89796. button is released. DragWindow calls this function before actually moving the window.
  89797. You can call it yourself to pull around the outline of any region, and then use the
  89798. information it returns to determine where to move the region.
  89799.  
  89800. On multiple-screen systems, the Window Manager now checks the screen rectangle
  89801. (screenBits.bounds) when the DragGrayRgn routine is called. This allows the object
  89802. being dragged to be positioned anywhere on the multiscreen desktop. If the dragging
  89803. bounds are based on screenBits.bound, the dragging boundsRect will be changed to the
  89804. bounding box of the grayRgn. The Window Manager’s criteria for modifying the bounds
  89805. are (1) the left, bottom, and right are within six pixels of screenBits.bound, and
  89806. (2) the top is within 36 pixels of screenBits.bounds.top. If the dragging bounds are
  89807. modified, the lmitRect parameter is also similarly modified.
  89808.  
  89809. Note:  DragGrayRgn alters the region; if you don’t want the original region
  89810.        changed, pass DragGrayRgn a handle to a copy.
  89811.  
  89812. The startPt parameter is assumed to be the point where the mouse button was originally
  89813. pressed, in the local coordinates of the current grafPort.
  89814.  
  89815. LmitRect and slopRect are also in the local coordinates of the current grafPort. To
  89816. explain these parameters, the concept of “offset point” must be introduced:  This is
  89817. initially the point whose vertical and horizontal offsets from the top left corner of
  89818. the region’s enclosing rectangle are the same as those of startPt. The offset point
  89819. follows the mouse location, except that DragGrayRgn will never move the offset point
  89820. outside limitRect; this limits the travel of the region’s outline (but not the movements
  89821. of the mouse). SlopRect, which should completely enclose limitRect, allows the user
  89822. some “slop” in moving the mouse. DragGrayRgn’s behavior while tracking the mouse
  89823. depends on the location of the mouse with respect to these two rectangles:
  89824.  
  89825.   •  When the mouse is inside lmitRect, the region’s outline follows it
  89826.      normally. If the mouse button is released there, the region should be
  89827.      moved to the mouse location.
  89828.   •  When the mouse is outside lmitRect but inside slopRect, DragGrayRgn
  89829.      “pins” the offset point to the edge of lmitRect. If the mouse button
  89830.      is released there, the region should be moved to this pinned location.
  89831.   •  When the mouse is outside slopRect, the outline disappears from the
  89832.      screen, but DragGrayRgn continues to follow the mouse; if it moves back
  89833.      into slopRect, the outline reappears. If the mouse button is released
  89834.      outside slopRect, the region should not be moved from its original
  89835.      position.
  89836.  
  89837. Figure 13 illustrates what happens when the mouse is moved outside lmitRect but
  89838. inside slopRect, for a rectangular region. The offset point is pinned as the mouse
  89839. location moves on.
  89840.  
  89841. If the mouse button is released within slopRect, the high-order word of the value
  89842. returned by DragGrayRgn contains the vertical coordinate of the ending mouse location
  89843. minus that of startPt and the low-order word contains the difference between the
  89844. horizontal coordinates. If the mouse button is released outside slopRect, both words
  89845. contain –32768 ($8000).
  89846.  
  89847. •••Refer to Figure 13.•••
  89848.  
  89849. Figure 13–DragGrayRgn Operation on a Rectangular Region
  89850.  
  89851. The axis parameter allows you to constrain the region’s motion to only one axis. It
  89852. has one of the following values:
  89853.  
  89854. CONST  noConstraint = 0;    {no constraint}
  89855.        hAxisOnly    = 1;    {horizontal axis only}
  89856.        vAxisOnly    = 2;    {vertical axis only}
  89857.  
  89858. If an axis constraint is in effect, the outline will follow the mouse’s movements
  89859. along the specified axis only, ignoring motion along the other axis. With or without
  89860. an axis constraint, the mouse must still be inside the slop rectangle for the outline
  89861. to appear at all.
  89862.  
  89863. The actionProc parameter is a pointer to a procedure that defines some action to be
  89864. performed repeatedly for as long as the user holds down the mouse button; the procedure
  89865. should have no parameters. If actionProc is NIL, DragGrayRgn simply retains control
  89866. until the mouse button is released.
  89867.  
  89868. Assembly-language note:  DragGrayRgn calls the procedure pointed to by the
  89869.                          global variable DragHook, if any, as long as the
  89870.                          mouse button is held down. (If there’s an actionProc
  89871.                          procedure, the actionProc procedure is called first.)
  89872.  
  89873.                          If you want the region’s outline to be drawn in a
  89874.                          pattern other than gray, you can store the pattern in
  89875.                          the global variable DragPattern and then invoke the
  89876.                          macro _DragTheRgn.
  89877.  
  89878. æKY dragwindow
  89879. æFc Windows.h
  89880. æT Function
  89881. æD void dragwindow(WindowPtr theWindow,Point *startPt,const Rect *boundsRect); 
  89882. æDT dragwindow((WindowPtr) theWindow,(Point *) startPt,(const Rect *) boundsRect);
  89883. æRI I-289, P-98, 169
  89884. æC  
  89885. When there’s a mouse-down event in the drag region of theWindow, the application
  89886. should call DragWindow with startPt equal to the point where the mouse button was
  89887. pressed (in global coordinates, as stored in the where field of the event record).
  89888. DragWindow pulls a dotted outline of theWindow around, following the movements of the
  89889. mouse until the button is released. When the mouse button is released, DragWindow
  89890. calls MoveWindow to move theWindow to the location to which it was dragged. If theWindow
  89891. isn’t the active window (and the Command key wasn’t being held down), DragWindow
  89892. makes it the active window by passing TRUE for the front parameter when calling
  89893. MoveWindow. If the Command key was being held down, the window is moved without being
  89894. made the active window.
  89895.  
  89896. BoundsRect is also given in global coordinates. If the mouse button is released when
  89897. the mouse location is outside the limits of boundsRect, DragWindow returns without
  89898. moving theWindow or making it the active window. For a document window, boundsRect
  89899. typically will be four pixels in from the menu bar and from the other edges of the
  89900. screen, to ensure that there won’t be less than a four-pixel-square area of the title
  89901. bar visible on the screen.
  89902.  
  89903. Assembly-language note:  As for TrackGoAway, if you store a pointer to a
  89904.                          procedure in the global variable DragHook, that
  89905.                          procedure will be called repeatedly while the user
  89906.                          holds down the mouse button. (DragWindow calls
  89907.                          DragGrayRgn, which calls the DragHook procedure).
  89908.  
  89909.  
  89910.